feat(media): support cloud codec via ffmpeg

Author: PIKACHUIM

cmd/worker/main.go

@@ -0,0 +1,167 @@
+# OpenList 转码协议 v1（自研）
+
+> 用于 OpenList Master 与远程 FFmpeg 转码 Worker 之间的通信。
+> 协议本身、所有依赖、推荐编码 (H.264/AV1) 均为开源免费，可商用。
+
+## 总览
+
+```
+Player ──► Master(/api/transcode/play) ──► Scheduler.Submit
+Worker ──► Master(/api/transcode/worker/register)             # 启动一次
+Worker ──► Master(/api/transcode/worker/heartbeat)            # 周期 10s
+Worker ──► Master(/api/transcode/worker/claim)                # 长轮询拉任务
+Worker ──► Master(/api/transcode/worker/segment)              # 流式回推切片
+Worker ──► Master(/api/transcode/worker/job/finish)           # 上报完成
+Player ──► Master(/tc/{job}/{token}/master.m3u8)              # 拉取播放列表
+Player ──► Master(/tc/{job}/{token}/{profile}/seg-N.ts)       # 拉取切片
+```
+
+## 通用约定
+- 所有请求体均为 JSON。
+- Worker 与 Master 间通过两类凭据鉴权：
+  - **shared_secret**（管理端 `transcode_worker_secret` 设置项）：用于 register / heartbeat / claim
+  - **callback_token**（Master 在 job 中下发，一次性）：用于 segment / job/finish
+- Header 形式：`Authorization: Bearer <token>`
+- 返回包统一使用 OpenList 通用响应：`{"code":200,"message":"success","data":{...}}`
+
+## 端点详细
+
+### POST /api/transcode/worker/register
+> 鉴权：Bearer = shared_secret
+
+请求：
+```json
+{
+  "name": "gpu-node-01",
+  "version": "1.0.0",
+  "capacity": 4,
+  "hwaccel": ["nvenc"],
+  "codecs_decode": ["h264","hevc","av1","vp9"],
+  "codecs_encode": ["h264","hevc"],
+  "max_resolution": "3840x2160",
+  "tags": ["linux","amd64"]
+}
+```
+
+响应：
+```json
+{
+  "code":200,"message":"success",
+  "data": {
+    "worker_id":"wk_xxx",
+    "heartbeat_interval":10,
+    "claim_strategy":"pull",
+    "protocol_version":"v1"
+  }
+}
+```
+
+### POST /api/transcode/worker/heartbeat
+> 鉴权：Bearer = shared_secret
+> 间隔：register 返回的 `heartbeat_interval`；服务端 30s 未收到则剔除 worker
+
+请求：
+```json
+{ "worker_id":"wk_xxx", "load":0.4, "running":["job_a"], "free_slots":3 }
+```
+
+响应：
+```json
+{ "code":200,"message":"success","data":{"ok":true,"kick":false,"cancel":["job_x"]}}
+```
+- `kick=true`：服务端要求 Worker 主动退出
+- `cancel`：需要 Worker 立刻终止的 job_ids（异步取消通道）
+
+### POST /api/transcode/worker/claim
+> 鉴权：Bearer = shared_secret
+> 长轮询：当无任务时，服务端最多挂起 `wait` 秒（最大 30）
+
+请求：
+```json
+{ "worker_id":"wk_xxx", "slots":1, "wait":20 }
+```
+
+响应：
+```json
+{ "code":200,"message":"success","data":{"jobs":[{
+  "id":"job_xxx",
+  "path":"/movies/x.mkv",
+  "source_url":"https://example.com/d/movies/x.mkv?sign=...",
+  "profiles":[{
+    "name":"1080p","video_codec":"h264","video_bitrate":"4000k",
+    "scale":"1920:-2","audio_codec":"aac","audio_bitrate":"160k",
+    "hwaccel":"nvenc"
+  }],
+  "output":{"format":"hls","segment_duration":6},
+  "callback_token":"tk_xxx",
+  "deadline":1731601234
+}]}}
+```
+
+### PUT /api/transcode/worker/segment
+> 鉴权：Bearer = callback_token
+> Query 参数：
+> - `job` 任务 ID
+> - `profile` profile 名（如 `1080p`）
+> - `seq` 切片序号（从 0 开始）
+> - `duration` 该切片秒数
+> - `final` 是否为最后一片（true/false）
+>
+> Body：原始 MPEG-TS 二进制（`Content-Type: video/mp2t`）
+
+响应：`204 No Content`
+
+### POST /api/transcode/worker/job/finish
+> 鉴权：Bearer = callback_token
+
+请求：
+```json
+{
+  "job_id":"job_xxx",
+  "status":"finished",
+  "error":"",
+  "stats":{"elapsed":312.4,"fps":120,"speed":2.1,"bytes_out":890123456}
+}
+```
+status 取值：`finished` / `failed` / `cancelled`
+
+## 播放端
+
+### POST /api/fs/transcode/play
+> 由前端播放器调用，用户登录态可见
+> 请求：`{"path":"/movies/x.mkv"}`
+>
+> 响应（无需转码）：
+> `{"transcode":false,"reason":"size below threshold"}`
+>
+> 响应（已下发转码任务）：
+> `{"transcode":true,"job_id":"job_xx","master_url":"https://.../tc/.../master.m3u8","profile":"1080p"}`
+
+### GET /tc/:job/:token/master.m3u8
+返回多档位主 m3u8。
+
+### GET /tc/:job/:token/:profile/playlist.m3u8
+阻塞等待首切片就绪（最多 30s）后返回 HLS 播放列表，未结束时不带 `#EXT-X-ENDLIST`。
+
+### GET /tc/:job/:token/:profile/seg-N.ts
+返回 N 号切片；如果尚未生成，最多等待 60s。
+
+## 启动远程 Worker
+
+```bash
+# 用 Master 配置中的 transcode_worker_secret 作为密钥
+go build -o openlist-worker ./cmd/worker
+
+./openlist-worker \
+  -master http://openlist.example.com:5244 \
+  -secret <transcode_worker_secret> \
+  -capacity 2 \
+  -hwaccel nvenc \
+  -ffmpeg /usr/bin/ffmpeg \
+  -workdir /tmp/openlist-worker
+```
+
+## License 说明
+- 协议：自研，可自由使用
+- FFmpeg：使用系统包提供的 LGPL 版本即可（含 libx264/libx265，libx264 是 GPL，建议在 Worker 镜像中遵循 GPL 公开/动态链接合规）
+- 推荐编码：H.264 互联网分发免授权 / AV1 永久免版税

docs/transcode-protocol.md

@@ -242,6 +242,69 @@ func InitialSettings() []model.SettingItem {
 		{Key: conf.StreamMaxClientUploadSpeed, Value: "-1", Type: conf.TypeNumber, Group: model.TRAFFIC, Flag: model.PRIVATE},
 		{Key: conf.StreamMaxServerDownloadSpeed, Value: "-1", Type: conf.TypeNumber, Group: model.TRAFFIC, Flag: model.PRIVATE},
 		{Key: conf.StreamMaxServerUploadSpeed, Value: "-1", Type: conf.TypeNumber, Group: model.TRAFFIC, Flag: model.PRIVATE},
+
+		// media settings
+		{Key: conf.MediaTMDBKey, Value: "", Type: conf.TypeString, Group: model.MEDIA, Flag: model.PRIVATE},
+		{Key: conf.MediaTMDBAPIURL, Value: "api.themoviedb.org", Type: conf.TypeString, Group: model.MEDIA, Flag: model.PRIVATE},
+		{Key: conf.MediaDiscogsToken, Value: "", Type: conf.TypeString, Group: model.MEDIA, Flag: model.PRIVATE},
+		{Key: conf.MediaDiscogsAPIURL, Value: "api.discogs.com", Type: conf.TypeString, Group: model.MEDIA, Flag: model.PRIVATE},
+		{Key: conf.MediaStoreThumbnail, Value: "false", Type: conf.TypeBool, Group: model.MEDIA, Flag: model.PRIVATE},
+		{Key: conf.MediaThumbnailMode, Value: "base64", Type: conf.TypeSelect, Options: "base64,local", Group: model.MEDIA, Flag: model.PRIVATE},
+		{Key: conf.MediaThumbnailPath, Value: "/imgs", Type: conf.TypeString, Group: model.MEDIA, Flag: model.PRIVATE},
+		{Key: conf.MediaScrapeConcurrency, Value: "5", Type: conf.TypeNumber, Group: model.MEDIA, Flag: model.PRIVATE},
+
+		// transcode settings (FFmpeg 云端/本地转码) - 默认全部关闭
+		{Key: conf.TranscodeEnabled, Value: "false", Type: conf.TypeBool, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `开启后，超过阈值的媒体文件将通过 FFmpeg 转码后再播放；默认关闭`},
+		{Key: conf.TranscodeRunMode, Value: "local", Type: conf.TypeSelect, Options: "local,remote,hybrid", Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `local=仅使用本机内置 worker；remote=只使用远程 Worker 节点；hybrid=本地优先，超载后派发到远程`},
+		{Key: conf.TranscodeMinSizeGB, Value: "5", Type: conf.TypeNumber, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `文件大于该 GB 数才走转码（小于则直链播放），0=任意大小都转码`},
+		{Key: conf.TranscodeMinBitrateMbps, Value: "20", Type: conf.TypeNumber, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `视频码率超过该 Mbps 才转码，0=不限制`},
+		{Key: conf.TranscodeSourceCodecs, Value: "hevc,h265,av1,vvc,vp9", Type: conf.TypeString, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `仅对这些源视频编码进行转码（逗号分隔）。常见高码率/兼容性差的编码：hevc,av1,vvc,vp9`},
+		{Key: conf.TranscodeSourceExtensions, Value: "mkv,ts,m2ts,mov,avi,wmv,flv,rmvb,webm", Type: conf.TypeString, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `仅对这些后缀进行转码（逗号分隔，不带点），mp4 默认不转码可直接播放`},
+		{Key: conf.TranscodeOutputFormat, Value: "hls", Type: conf.TypeSelect, Options: "hls,dash,mp4", Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `输出封装格式，HLS 兼容性最好`},
+		{Key: conf.TranscodeOutputCodec, Value: "h264", Type: conf.TypeSelect, Options: "h264,hevc,av1", Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `重新编码后的视频编码，推荐 h264（最广兼容、互联网分发免授权费）`},
+		{Key: conf.TranscodeOutputBitrate, Value: "4000k", Type: conf.TypeString, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `输出视频码率，例如 4000k / 6M。建议 1080p:4000k、720p:2500k`},
+		{Key: conf.TranscodeOutputAudioCodec, Value: "aac", Type: conf.TypeSelect, Options: "aac,mp3,opus,copy", Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `输出音频编码，aac 兼容性最好；copy=直接复制源音频流`},
+		{Key: conf.TranscodeOutputAudioBitrate, Value: "160k", Type: conf.TypeString, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `输出音频码率`},
+		{Key: conf.TranscodeOutputResolution, Value: "1920x1080", Type: conf.TypeSelect, Options: "source,3840x2160,2560x1440,1920x1080,1280x720,854x480", Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `输出分辨率上限，超过该分辨率会下采样；source=保持源分辨率`},
+		{Key: conf.TranscodeSegmentDuration, Value: "6", Type: conf.TypeNumber, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `HLS/DASH 切片时长(秒)，越小首帧越快但请求数变多，推荐 4-10`},
+		{Key: conf.TranscodeHWAccel, Value: "none", Type: conf.TypeSelect,
+			Options: "none,auto,nvenc,qsv,vaapi,amf,videotoolbox",
+			Group:   model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `GPU 硬件加速：
+none = 纯 CPU(libx264)
+auto = 自动探测可用加速器
+nvenc = NVIDIA GPU(GeForce/Tesla/Quadro/RTX,需 NVIDIA 驱动)
+qsv = Intel 集显/独显 QuickSync(免费,功耗低)
+vaapi = Linux 通用 VA-API(支持 Intel/AMD)
+amf = AMD GPU(Windows AMF)
+videotoolbox = macOS 硬件加速`},
+		{Key: conf.TranscodeFFmpegPath, Value: "ffmpeg", Type: conf.TypeString, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `FFmpeg 可执行路径，留空则使用 PATH 中的 ffmpeg`},
+		{Key: conf.TranscodeFFprobePath, Value: "ffprobe", Type: conf.TypeString, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `FFprobe 可执行路径`},
+		{Key: conf.TranscodeWorkerSecret, Value: "", Type: conf.TypeString, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `远程 Worker 注册时使用的共享密钥，留空则禁用远程 Worker 注册`},
+		{Key: conf.TranscodeCachePath, Value: "data/transcode_cache", Type: conf.TypeString, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `转码切片缓存目录`},
+		{Key: conf.TranscodeCacheMaxGB, Value: "20", Type: conf.TypeNumber, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `切片缓存最大容量(GB)，超过后按 LRU 清理`},
+		{Key: conf.TranscodeJobTimeoutMin, Value: "120", Type: conf.TypeNumber, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `单个转码任务超时分钟数，超时自动失败`},
+		{Key: conf.TranscodeLocalConcurrency, Value: "1", Type: conf.TypeNumber, Group: model.TRANSCODE, Flag: model.PRIVATE,
+			Help: `本机内置 worker 同时执行的转码任务数(local/hybrid 模式生效)`},
 	}
 	additionalSettingItems := tool.Tools.Items()
 	// 固定顺序

internal/bootstrap/data/setting.go

@@ -15,6 +15,7 @@ import (
 	"github.com/OpenListTeam/OpenList/v4/internal/conf"
 	"github.com/OpenListTeam/OpenList/v4/internal/db"
 	"github.com/OpenListTeam/OpenList/v4/internal/fs"
+	"github.com/OpenListTeam/OpenList/v4/internal/transcode"
 	"github.com/OpenListTeam/OpenList/v4/pkg/utils"
 	"github.com/OpenListTeam/OpenList/v4/server"
 	"github.com/OpenListTeam/OpenList/v4/server/middlewares"
@@ -92,6 +93,10 @@ func Start() {
 	InitOfflineDownloadTools()
 	LoadStorages()
 	InitTaskManager()
+	// 初始化转码模块（总开关关时也会启动 manager，但本地 worker 仅在 enabled 时由 Manager.Start 内部按 run_mode 启动）
+	if transcode.IsEnabled() {
+		transcode.Default().Start()
+	}
 	if !flags.Debug && !flags.Dev {
 		gin.SetMode(gin.ReleaseMode)
 	}

internal/bootstrap/run.go

@@ -161,6 +161,40 @@ const (
 	StreamMaxClientUploadSpeed            = "max_client_upload_speed"
 	StreamMaxServerDownloadSpeed          = "max_server_download_speed"
 	StreamMaxServerUploadSpeed            = "max_server_upload_speed"
+
+	// media
+	MediaTMDBKey          = "media_tmdb_key"
+	MediaTMDBAPIURL       = "media_tmdb_api_url"
+	MediaDiscogsToken     = "media_discogs_token"
+	MediaDiscogsAPIURL    = "media_discogs_api_url"
+	MediaThumbnailMode    = "media_thumbnail_mode"
+	MediaThumbnailPath    = "media_thumbnail_path"
+	MediaStoreThumbnail   = "media_store_thumbnail"
+	MediaScrapeConcurrency = "media_scrape_concurrency"
+
+	// transcode (云端/本地 FFmpeg 转码)
+	TranscodeEnabled            = "transcode_enabled"              // 总开关，默认关
+	TranscodeMinSizeGB          = "transcode_min_size_gb"          // 文件大于多少 GB 才转码
+	TranscodeMinBitrateMbps     = "transcode_min_bitrate_mbps"     // 视频码率高于多少 Mbps 才转码（0=不限）
+	TranscodeSourceCodecs       = "transcode_source_codecs"        // 仅对这些源编码进行转码
+	TranscodeSourceExtensions   = "transcode_source_extensions"    // 仅对这些后缀进行转码
+	TranscodeOutputFormat       = "transcode_output_format"        // 输出封装格式 hls/dash/mp4
+	TranscodeOutputCodec        = "transcode_output_codec"         // 重新编码的视频编码
+	TranscodeOutputBitrate      = "transcode_output_bitrate"       // 输出视频码率，例如 4000k
+	TranscodeOutputAudioCodec   = "transcode_output_audio_codec"   // 输出音频编码
+	TranscodeOutputAudioBitrate = "transcode_output_audio_bitrate" // 输出音频码率，例如 160k
+	TranscodeOutputResolution   = "transcode_output_resolution"    // 输出分辨率上限
+	TranscodeSegmentDuration    = "transcode_segment_duration"     // HLS 切片时长(秒)
+	TranscodeHWAccel            = "transcode_hwaccel"              // 硬件加速类型 none/auto/nvenc/qsv/vaapi/amf/videotoolbox
+	TranscodeFFmpegPath         = "transcode_ffmpeg_path"          // 自定义 ffmpeg 可执行路径
+	TranscodeFFprobePath        = "transcode_ffprobe_path"         // 自定义 ffprobe 可执行路径
+	TranscodeRunMode            = "transcode_run_mode"             // local / remote / hybrid
+	TranscodeWorkerSecret       = "transcode_worker_secret"        // 远程 Worker 共享密钥
+	TranscodeCachePath          = "transcode_cache_path"           // 切片缓存目录
+	TranscodeCacheMaxGB         = "transcode_cache_max_gb"         // 缓存最大占用，超出 LRU 淘汰
+	TranscodeJobTimeoutMin      = "transcode_job_timeout_min"      // 单个任务超时分钟
+	TranscodeLocalConcurrency   = "transcode_local_concurrency"    // 本地内置 worker 并发数(run_mode=local/hybrid 时生效)
+	TranscodeIdleTimeoutSec     = "transcode_idle_timeout_sec"     // 播放端无请求多少秒后自动停止转码（默认90秒）
 )
 
 const (

internal/conf/const.go

@@ -13,6 +13,8 @@ const (
 	S3
 	FTP
 	TRAFFIC
+	MEDIA
+	TRANSCODE
 )
 
 const (