leduchuong/tikplayer repository overview

⁠Tikplayer 2.6

中文 | English⁠

Tikplayer 是一款面向 NAS、HomeLab 和自托管用户的手机优先媒体播放器，支持 OpenList/AList 与 WebDAV 媒体源。它重点解决私人媒体库在手机端日常使用里的几个痛点：大文件直放启动慢、目录播放混入图片素材、安卓进度条拖动容易和系统手势冲突、从文件页播放后难以回到随机播放。Tikplayer 保持首屏就是播放器，通过直放优先、HLS 兜底、移动端触控优化和本地化凭据保存，让 NAS 媒体更接近日常刷视频体验。相比反复在 OpenList 文件页之间切换，它更适合作为个人 NAS 视频播放入口。

⁠为什么做它？

很多 NAS 文件索引能把文件暴露出来，但并不像一个真正每天会用的手机播放器。大体积 MP4 可能卡在起播阶段，Android 边缘返回和底部主页手势会抢走进度条拖动，文件夹临时播放会打断随机播放流程，图片封面还可能被误放进视频队列。Tikplayer 把这些粗糙边角收拢成一个专注的 PWA：打开即播放、可随机、可进目录、可收藏、可删除，也能在文件页播放结束后回到随机播放。

⁠2.6 版本亮点

• 更新浅色 PWA 图标，并为 manifest 与图标链接加入缓存破除参数，降低客户端继续使用旧图标的概率。
• 安卓进度条改为抬高并内缩的独立 seek rail，避开系统边缘返回和底部导航热区。
• 文件页右上角播放会创建临时文件夹播放列表，并提供返回随机播放的入口。
• MP4 progressive 直放保留 Range/HEAD 语义，慢启动或不可直放时可走 HLS 兜底。
• 文件夹播放会过滤封面、背景图等图片素材，不再把图片伪装成视频入队。

⁠界面预览

应用启动后直接进入全屏移动端播放器，包含底部导航、右侧播放操作、独立进度条、媒体源管理、文件浏览、收藏和删除等工作流。公开包没有附带真实截图，避免把 NAS 路径、文件名、媒体封面或缩略图发布到公共仓库。

⁠快速开始

docker run -d --name tikplayer -p 8080:8000 -v tikplayer-data:/app/data --restart unless-stopped leduchuong/tikplayer:2.6

打开 http://localhost:8080，添加 OpenList/AList 或 WebDAV 媒体源，然后扫描你的媒体目录。

⁠Docker Compose

services:
  tikplayer:
    image: leduchuong/tikplayer:2.6
    container_name: tikplayer
    restart: unless-stopped
    ports:
      - "8080:8000"
    env_file:
      - .env
    devices:
      - /dev/dri:/dev/dri
    group_add:
      - "44"
      - "109"
    environment:
      - LIBVA_DRIVER_NAME=iHD
      - TRANSCODE_BACKENDS=qsv,vaapi,cpu
    volumes:
      - tikplayer-data:/app/data
      - tikplayer-image:/app/image
    shm_size: "2gb"

volumes:
  tikplayer-data:
  tikplayer-image:

⁠配置说明

复制 .env.example 为 .env，修改管理员密码哈希，然后在 Web 界面中添加你自己的 OpenList/AList 或 WebDAV 来源。生产环境建议配置 ALLOWED_ALIST_HOSTS，限制服务端可访问的上游媒体源域名，减少误配和滥用风险。

⁠升级方式

拉取新镜像并重建容器，继续保留 /app/data 数据卷。PWA 用户升级后可能需要刷新一次，让新的 service worker、manifest 和图标缓存生效。

⁠项目结构

• main.py：FastAPI 后端、媒体源管理、流代理、HLS 兜底和 token 持久化。
• index.html：PWA 外壳与自定义播放器界面。
• sw.js：Service Worker 缓存策略。
• static/playback-policy.js：播放路由和兜底策略辅助逻辑。
• tests/ 与 test_*：前端和后端契约测试。

⁠GitHub Topics

建议主题：nas、homelab、selfhosted、webdav、alist、openlist、pwa、media-server。

⁠支持与免责声明

Tikplayer 仅用于你有权访问和播放的个人媒体与服务器。不要在公共仓库、截图或日志中发布真实服务器地址、账号、密码、token、cookie、内部路径或 NAS 文件名。完整免责声明见 DISCLAIMER.md⁠。