ma303973022/junyao-ktv repository overview

骏耀K歌 · junyao-ktv

局域网自建 KTV 点歌系统。一台机器 + Docker，就能在家里/小型场所搭出电视端点歌、手机扫码点歌、后台曲库管理的完整一套，MV 支持本地目录和网盘/网络路径（含 STRM）两种来源，播放端自带原唱/伴唱切换、HLS 硬件转码加速。

功能特性

三端合一：TV 播放端（电视/投影仪全屏播放）、手机扫码点歌端（无需安装 App）、Web 曲库管理后台，三者通过同一个容器、同一个端口提供。

原唱/伴唱切换：源文件有真实双音轨时走 HLS 多音轨切换；只有单音轨立体声源时自动降级为 Web Audio 声道复制兜底，两种模式对用户都是无感的一键切换。

硬件转码加速：默认支持核显 VAAPI 硬件编解码，检测不到硬件时自动回退纯软件编码；也可选启用 NVIDIA NVENC。 本地曲库 + 网盘/STRM 曲库：本地 MV 文件和网盘挂载目录（fnOS 网盘挂载、rclone、alist 等）、.strm 指针文件都能作为曲库来源混用，网络路径播放前会先缓存到本地，避免慢速网盘拖垮探测/播放，缓存策略（空间上限、保留天数、并发数）后台可调。

自定义文件名解析：曲库管理后台支持按自己曲库真实的命名习惯自定义解析模板，一键从文件名批量提取歌手/歌名/语种/风格，支持"歌手&歌手"这类多歌手写法。

歌手头像：按歌手名放对应图片即可在 TV 端「歌星」列表显示真人头像，没有配图自动用姓名首字兜底。

点歌队列 / 历史 / 收藏：手机端点歌、置顶、删除，播放历史和收藏记录持久化保存。

启动后访问 http://宿主机IP:8083⁠ 即为导航页，包含 TV 播放端、曲库管理后台、手机点歌二维码入口。

/mv、/mv-net 挂进去之后，具体启用哪些子文件夹作为曲库来源、网络路径是否走本地缓存，都在「曲库管理」后台的「曲库来源」面板里配置，保存后立即生效，不需要重启或重建容器。

安卓客户端：https://github.com/ma303973022/junyao-ktv⁠