mediakit-cli 0.1.3__tar.gz → 0.1.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/PKG-INFO +246 -223
  2. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/README.md +185 -162
  3. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/__init__.py +1 -1
  4. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli.egg-info/PKG-INFO +246 -223
  5. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/pyproject.toml +77 -77
  6. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/setup.cfg +4 -4
  7. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/tests/test_auto.py +32 -32
  8. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/tests/test_config.py +29 -29
  9. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/tests/test_edit_math.py +28 -28
  10. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/tests/test_subs.py +44 -44
  11. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/LICENSE +0 -0
  12. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/__main__.py +0 -0
  13. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/auto.py +0 -0
  14. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/cli.py +0 -0
  15. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/config.py +0 -0
  16. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/dub.py +0 -0
  17. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/edit.py +0 -0
  18. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/index.py +0 -0
  19. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/lyrics.py +0 -0
  20. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/mcp_server.py +0 -0
  21. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/music.py +0 -0
  22. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/ocr.py +0 -0
  23. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/polish.py +0 -0
  24. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/probe.py +0 -0
  25. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/shotcard.py +0 -0
  26. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/shots.py +0 -0
  27. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/subs.py +0 -0
  28. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/util.py +0 -0
  29. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/vlm.py +0 -0
  30. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli/watch.py +0 -0
  31. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli.egg-info/SOURCES.txt +0 -0
  32. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli.egg-info/dependency_links.txt +0 -0
  33. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli.egg-info/entry_points.txt +0 -0
  34. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli.egg-info/requires.txt +0 -0
  35. {mediakit_cli-0.1.3 → mediakit_cli-0.1.4}/mediakit_cli.egg-info/top_level.txt +0 -0
@@ -1,223 +1,246 @@
1
- Metadata-Version: 2.4
2
- Name: mediakit-cli
3
- Version: 0.1.3
4
- Summary: Agent-friendly CLI for watching videos, analyzing music, subtitling, dubbing and beat-synced editing.
5
- Author: mediakit contributors
6
- License-Expression: MIT
7
- Project-URL: Homepage, https://github.com/Lee2277-t/mediakit
8
- Project-URL: Repository, https://github.com/Lee2277-t/mediakit
9
- Project-URL: Issues, https://github.com/Lee2277-t/mediakit/issues
10
- Keywords: video,subtitles,ffmpeg,whisper,agent,mcp
11
- Classifier: Programming Language :: Python :: 3
12
- Classifier: Operating System :: OS Independent
13
- Classifier: Topic :: Multimedia :: Video
14
- Classifier: Topic :: Multimedia :: Sound/Audio
15
- Requires-Python: >=3.10
16
- Description-Content-Type: text/markdown
17
- License-File: LICENSE
18
- Requires-Dist: numpy>=1.24
19
- Requires-Dist: pillow>=10
20
- Requires-Dist: pysubs2>=1.6
21
- Provides-Extra: asr
22
- Requires-Dist: faster-whisper>=1.0; extra == "asr"
23
- Provides-Extra: vision
24
- Requires-Dist: opencv-python>=4.8; extra == "vision"
25
- Requires-Dist: scenedetect>=0.6; extra == "vision"
26
- Requires-Dist: rapidocr-onnxruntime>=1.3; extra == "vision"
27
- Provides-Extra: timeline
28
- Requires-Dist: opentimelineio>=0.16; extra == "timeline"
29
- Provides-Extra: dl
30
- Requires-Dist: yt-dlp>=2024.1.1; extra == "dl"
31
- Provides-Extra: music
32
- Requires-Dist: librosa>=0.10; extra == "music"
33
- Requires-Dist: scipy>=1.10; extra == "music"
34
- Requires-Dist: soundfile>=0.12; extra == "music"
35
- Provides-Extra: separate
36
- Requires-Dist: audio-separator>=0.20; extra == "separate"
37
- Provides-Extra: search
38
- Requires-Dist: open-clip-torch>=2.20; extra == "search"
39
- Provides-Extra: mcp
40
- Requires-Dist: mcp>=1.0; extra == "mcp"
41
- Provides-Extra: windows
42
- Requires-Dist: pywin32>=306; sys_platform == "win32" and extra == "windows"
43
- Provides-Extra: all
44
- Requires-Dist: faster-whisper>=1.0; extra == "all"
45
- Requires-Dist: opencv-python>=4.8; extra == "all"
46
- Requires-Dist: scenedetect>=0.6; extra == "all"
47
- Requires-Dist: rapidocr-onnxruntime>=1.3; extra == "all"
48
- Requires-Dist: opentimelineio>=0.16; extra == "all"
49
- Requires-Dist: yt-dlp>=2024.1.1; extra == "all"
50
- Requires-Dist: librosa>=0.10; extra == "all"
51
- Requires-Dist: scipy>=1.10; extra == "all"
52
- Requires-Dist: soundfile>=0.12; extra == "all"
53
- Requires-Dist: audio-separator>=0.20; extra == "all"
54
- Requires-Dist: open-clip-torch>=2.20; extra == "all"
55
- Requires-Dist: mcp>=1.0; extra == "all"
56
- Requires-Dist: pywin32>=306; sys_platform == "win32" and extra == "all"
57
- Provides-Extra: dev
58
- Requires-Dist: pytest>=7.4; extra == "dev"
59
- Requires-Dist: ruff>=0.4; extra == "dev"
60
- Dynamic: license-file
61
-
62
- # mediakit
63
-
64
- **One CLI, 17 commands, JSON out — for agents that need to watch, listen, subtitle and cut.**
65
-
66
- `mediakit` is a thin orchestration layer over mature media tools. It does not
67
- reimplement decoding, ASR or scene detection; it calls them and returns
68
- structured results an agent can reason about, plus an MCP server so the whole
69
- toolkit can be attached to any MCP client.
70
-
71
- ```
72
- $ mk watch clip.mp4 --out work/clip --lang zh --ocr
73
- 语言 zh · 4 镜头 · 12 关键帧 · 转写 8 段 · 画面文字 2 条
74
- $ mk search work/clip/index "穿黑裙子的女孩在草地上" --top 3
75
- 42.50s score 0.311 ...
76
- ```
77
-
78
- [中文说明](README.zh-CN.md)
79
-
80
- ## Why another wrapper?
81
-
82
- Most tools are excellent at one step and then stop: PySceneDetect prints a
83
- table, Whisper emits one long line, CLIP libraries return tensors. An agent
84
- needs the opposite: short, composable commands with stable JSON, and no GUI.
85
-
86
- | Upstream | What it does | What `mk` adds |
87
- |---|---|---|
88
- | PySceneDetect | shot boundaries | `contact.jpg`, `shots.json`, OTIO export |
89
- | faster-whisper | segments + words | pause-based line breaking, width limits, 繁→简, karaoke, QA |
90
- | ffmpeg | encode/cut/burn | one plan file, xfade + acrossfade, subtitle rescaling |
91
- | RapidOCR | text boxes | frame sampling, de-dup, SRT output |
92
- | CLIP | embeddings | index/search commands with thumbnails |
93
- | librosa | tempo/beats | tempogram tempo prior, sections, chords, melody |
94
- | VideoCaptioner | LLM subtitle polish | one command, local Ollama, bilingual output |
95
-
96
- ## Install
97
-
98
- ```bash
99
- pip install "mediakit-cli[all]" # everything
100
- pip install mediakit-cli # core only: probe, edit, auto, plan logic
101
- ```
102
-
103
- `ffmpeg` must be on `PATH` (or set `MEDIAKIT_FFMPEG`). Optional groups:
104
-
105
- The distribution is named `mediakit-cli`; the Python import package is
106
- `mediakit_cli` (to avoid a collision with the unrelated PyPI package
107
- `mediakit`). The CLI command is `mk` either way.
108
-
109
- | Extra | Enables | Install |
110
- |---|---|---|
111
- | `asr` | `subs`, `watch`, `lyrics` | `faster-whisper` |
112
- | `vision` | `shots`, `shotcard`, `ocr` | OpenCV, PySceneDetect, RapidOCR |
113
- | `music` | `music` | librosa |
114
- | `search` | `index`, `search` | open_clip + ViT-B-32 weights |
115
- | `separate` | `lyrics --separate` | audio-separator |
116
- | `mcp` | `mediakit-mcp` | MCP SDK |
117
- | `windows` | `dub`, `voices` | pywin32 + SAPI |
118
- | `timeline` | `shots --otio` | OpenTimelineIO |
119
-
120
- Environment overrides: `MEDIAKIT_FFMPEG`, `MEDIAKIT_AUDIO_SEPARATOR`,
121
- `MEDIAKIT_VIDEOCAPTIONER`, `MEDIAKIT_OLLAMA_BASE`, `MEDIAKIT_VLM_MODEL`.
122
-
123
- ## Commands
124
-
125
- ```bash
126
- # look
127
- mk probe a.mp4
128
- mk watch a.mp4 --out work/a --lang zh --ocr
129
- mk frames a.mp4 --n 12 --out work/a/frames
130
- mk ocr a.mp4 --out work/a/ocr --every 2
131
- mk index a.mp4 --out work/a/index
132
- mk search work/a/index "a girl running on grass"
133
-
134
- # listen
135
- mk music song.mp3 --chords --melody --engine beat-this
136
- mk lyrics song.mp3 --out work/lyrics --lang ja
137
-
138
- # dissect
139
- mk shots a.mp4 --out work/a --otio
140
- mk shotcard a.mp4 --out work/a/card --vlm
141
-
142
- # subtitle
143
- mk subs a.mp4 --lang zh --out work/a --size 1080x1920 --max-chars 12 --karaoke --qa
144
- mk subqa work/a/subs.srt
145
- mk polish work/a/subs.srt --out work/a/polished.srt
146
- mk voices
147
- mk dub a.mp4 --srt work/a/subs.srt --out work/dub.mp4 --voice Huihui --mix-original
148
-
149
- # cut
150
- mk edit work/plan.json --out work/final.mp4
151
- mk auto --music bgm.mp3 --src footage --out work/mv.mp4 --transition fade
152
- ```
153
-
154
- Every command accepts `--json`. Without it you get a short human summary.
155
-
156
- ### `mk auto` — beat-synced montage
157
-
158
- Analyzes the track, decides how many beats per cut per section (quiet sections
159
- get longer cuts, loud ones shorter), picks shots from a folder, snaps cuts to
160
- beats and renders `xfade` transitions with matching `acrossfade` audio.
161
-
162
- ```bash
163
- mk auto --music bgm.mp3 --src footage --out mv.mp4 \
164
- --size 1080x1920 --fit crop --transition fade --seed 7
165
- mk auto --music bgm.mp3 --src footage --out mv.mp4 --plan-only # plan only
166
- ```
167
-
168
- ## MCP server
169
-
170
- ```json
171
- {
172
- "mcpServers": {
173
- "mediakit": { "command": "mediakit-mcp" }
174
- }
175
- }
176
- ```
177
-
178
- 12 tools: `probe`, `shots`, `music`, `subs`, `ocr`, `shotcard`, `index`,
179
- `search`, `lyrics`, `dub`, `edit`, `auto`.
180
-
181
- ## Measured, not assumed
182
-
183
- Numbers below were produced on a local machine (CPU) with the benchmark
184
- scripts in `tools/`. They are small-sample results, not leaderboard claims.
185
-
186
- | Area | Result |
187
- |---|---|
188
- | Shot detection | 3 hard cuts detected at exactly 4.00s / 8.00s |
189
- | Subtitles | 16.5s Chinese speech → 9 lines, traditional→simplified, width capped |
190
- | Karaoke | `\kf` per word; at 0.2s 65% of subtitle pixels still unsung color |
191
- | OCR | read burned subtitles back as 「大家晚上好。」and merged into SRT |
192
- | Retrieval (synthetic, 8 segments) | recall@1 75% descriptive / 88% short, recall@3 100% |
193
- | Retrieval (real footage, 8 clips) | recall@1 75%, recall@3 100% |
194
- | Lyric CER vs reference subs | mix 89.7% → vocals 60.3% (small) → **54.4% (medium)** |
195
- | Tempo correction | librosa default 103.36 BPM was a 4:3 artifact; tempogram prior → 80.75 BPM |
196
- | Montage | 7 segments from a 20s track; 18.50s with 6×0.25s fades |
197
- | Audio crossfade | 3×2s clips + 0.25s fade + keep_audio → 5.50s, audio kept |
198
- | Dubbing | 9 lines → 18.60s output, full length, 2ch/48kHz |
199
-
200
- ## Known limits
201
-
202
- - Retrieval benchmarks are small (8 segments/clips) and CLIP is
203
- phrasing-sensitive; low-information frames (pure white/black) fail.
204
- - Singing transcription is still hard: 54% CER is the good case.
205
- - `dub` uses Windows SAPI — robotic, and long lines are time-compressed at most 2×.
206
- - VLM shot descriptions were validated on a handful of frames.
207
- - `beat_this` and librosa often disagree by a few BPM; the package now anchors
208
- tempo with a tempogram prior but does not prove which tracker is musically right.
209
- - Transition handling assumes hard cuts when detecting shots.
210
-
211
- ## Layout
212
-
213
- ```
214
- mediakit_cli/ package (17 modules + MCP server)
215
- tools/ benchmarks: retrieval, lyrics CER, tempo
216
- docs/ architecture and data contracts
217
- examples/ sample edit plan
218
- tests/ unit tests for pure logic
219
- ```
220
-
221
- ## License
222
-
223
- MIT
1
+ Metadata-Version: 2.4
2
+ Name: mediakit-cli
3
+ Version: 0.1.4
4
+ Summary: Agent-friendly CLI for watching videos, analyzing music, subtitling, dubbing and beat-synced editing.
5
+ Author: mediakit contributors
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Lee2277-t/mediakit
8
+ Project-URL: Repository, https://github.com/Lee2277-t/mediakit
9
+ Project-URL: Issues, https://github.com/Lee2277-t/mediakit/issues
10
+ Keywords: video,subtitles,ffmpeg,whisper,agent,mcp
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Topic :: Multimedia :: Video
14
+ Classifier: Topic :: Multimedia :: Sound/Audio
15
+ Requires-Python: >=3.10
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Requires-Dist: numpy>=1.24
19
+ Requires-Dist: pillow>=10
20
+ Requires-Dist: pysubs2>=1.6
21
+ Provides-Extra: asr
22
+ Requires-Dist: faster-whisper>=1.0; extra == "asr"
23
+ Provides-Extra: vision
24
+ Requires-Dist: opencv-python>=4.8; extra == "vision"
25
+ Requires-Dist: scenedetect>=0.6; extra == "vision"
26
+ Requires-Dist: rapidocr-onnxruntime>=1.3; extra == "vision"
27
+ Provides-Extra: timeline
28
+ Requires-Dist: opentimelineio>=0.16; extra == "timeline"
29
+ Provides-Extra: dl
30
+ Requires-Dist: yt-dlp>=2024.1.1; extra == "dl"
31
+ Provides-Extra: music
32
+ Requires-Dist: librosa>=0.10; extra == "music"
33
+ Requires-Dist: scipy>=1.10; extra == "music"
34
+ Requires-Dist: soundfile>=0.12; extra == "music"
35
+ Provides-Extra: separate
36
+ Requires-Dist: audio-separator>=0.20; extra == "separate"
37
+ Provides-Extra: search
38
+ Requires-Dist: open-clip-torch>=2.20; extra == "search"
39
+ Provides-Extra: mcp
40
+ Requires-Dist: mcp>=1.0; extra == "mcp"
41
+ Provides-Extra: windows
42
+ Requires-Dist: pywin32>=306; sys_platform == "win32" and extra == "windows"
43
+ Provides-Extra: all
44
+ Requires-Dist: faster-whisper>=1.0; extra == "all"
45
+ Requires-Dist: opencv-python>=4.8; extra == "all"
46
+ Requires-Dist: scenedetect>=0.6; extra == "all"
47
+ Requires-Dist: rapidocr-onnxruntime>=1.3; extra == "all"
48
+ Requires-Dist: opentimelineio>=0.16; extra == "all"
49
+ Requires-Dist: yt-dlp>=2024.1.1; extra == "all"
50
+ Requires-Dist: librosa>=0.10; extra == "all"
51
+ Requires-Dist: scipy>=1.10; extra == "all"
52
+ Requires-Dist: soundfile>=0.12; extra == "all"
53
+ Requires-Dist: audio-separator>=0.20; extra == "all"
54
+ Requires-Dist: open-clip-torch>=2.20; extra == "all"
55
+ Requires-Dist: mcp>=1.0; extra == "all"
56
+ Requires-Dist: pywin32>=306; sys_platform == "win32" and extra == "all"
57
+ Provides-Extra: dev
58
+ Requires-Dist: pytest>=7.4; extra == "dev"
59
+ Requires-Dist: ruff>=0.4; extra == "dev"
60
+ Dynamic: license-file
61
+
62
+ # mediakit
63
+
64
+ **One CLI, 17 commands, JSON out — for agents that need to watch, listen, subtitle and cut.**
65
+
66
+ `mediakit` is a thin orchestration layer over mature media tools. It does not
67
+ reimplement decoding, ASR or scene detection; it calls them and returns
68
+ structured results an agent can reason about, plus an MCP server so the whole
69
+ toolkit can be attached to any MCP client.
70
+
71
+ ```
72
+ $ mk watch clip.mp4 --out work/clip --lang zh --ocr
73
+ 语言 zh · 4 镜头 · 12 关键帧 · 转写 8 段 · 画面文字 2 条
74
+ $ mk search work/clip/index "穿黑裙子的女孩在草地上" --top 3
75
+ 42.50s score 0.311 ...
76
+ ```
77
+
78
+ [中文说明](README.zh-CN.md)
79
+
80
+ ## Why another wrapper?
81
+
82
+ Most tools are excellent at one step and then stop: PySceneDetect prints a
83
+ table, Whisper emits one long line, CLIP libraries return tensors. An agent
84
+ needs the opposite: short, composable commands with stable JSON, and no GUI.
85
+
86
+ | Upstream | What it does | What `mk` adds |
87
+ |---|---|---|
88
+ | PySceneDetect | shot boundaries | `contact.jpg`, `shots.json`, OTIO export |
89
+ | faster-whisper | segments + words | pause-based line breaking, width limits, 繁→简, karaoke, QA |
90
+ | ffmpeg | encode/cut/burn | one plan file, xfade + acrossfade, subtitle rescaling |
91
+ | RapidOCR | text boxes | frame sampling, de-dup, SRT output |
92
+ | CLIP | embeddings | index/search commands with thumbnails |
93
+ | librosa | tempo/beats | tempogram tempo prior, sections, chords, melody |
94
+ | VideoCaptioner | LLM subtitle polish | one command, local Ollama, bilingual output |
95
+
96
+ ## Install
97
+
98
+ ```bash
99
+ pip install "mediakit-cli[all]" # everything
100
+ pip install mediakit-cli # core only: probe, edit, auto, plan logic
101
+ ```
102
+
103
+ `ffmpeg` must be on `PATH` (or set `MEDIAKIT_FFMPEG`). Optional groups:
104
+
105
+ The distribution is named `mediakit-cli`; the Python import package is
106
+ `mediakit_cli` (to avoid a collision with the unrelated PyPI package
107
+ `mediakit`). The CLI command is `mk` either way.
108
+
109
+ | Extra | Enables | Install |
110
+ |---|---|---|
111
+ | `asr` | `subs`, `watch`, `lyrics` | `faster-whisper` |
112
+ | `vision` | `shots`, `shotcard`, `ocr` | OpenCV, PySceneDetect, RapidOCR |
113
+ | `music` | `music` | librosa |
114
+ | `search` | `index`, `search` | open_clip + ViT-B-32 weights |
115
+ | `separate` | `lyrics --separate` | audio-separator |
116
+ | `mcp` | `mediakit-mcp` | MCP SDK |
117
+ | `windows` | `dub`, `voices` | pywin32 + SAPI |
118
+ | `timeline` | `shots --otio` | OpenTimelineIO |
119
+
120
+ Environment overrides: `MEDIAKIT_FFMPEG`, `MEDIAKIT_AUDIO_SEPARATOR`,
121
+ `MEDIAKIT_VIDEOCAPTIONER`, `MEDIAKIT_OLLAMA_BASE`, `MEDIAKIT_VLM_MODEL`.
122
+
123
+ ## Commands
124
+
125
+ ```bash
126
+ # look
127
+ mk probe a.mp4
128
+ mk watch a.mp4 --out work/a --lang zh --ocr
129
+ mk frames a.mp4 --n 12 --out work/a/frames
130
+ mk ocr a.mp4 --out work/a/ocr --every 2
131
+ mk index a.mp4 --out work/a/index
132
+ mk search work/a/index "a girl running on grass"
133
+
134
+ # listen
135
+ mk music song.mp3 --chords --melody --engine beat-this
136
+ mk lyrics song.mp3 --out work/lyrics --lang ja
137
+
138
+ # dissect
139
+ mk shots a.mp4 --out work/a --otio
140
+ mk shotcard a.mp4 --out work/a/card --vlm
141
+
142
+ # subtitle
143
+ mk subs a.mp4 --lang zh --out work/a --size 1080x1920 --max-chars 12 --karaoke --qa
144
+ mk subqa work/a/subs.srt
145
+ mk polish work/a/subs.srt --out work/a/polished.srt
146
+ mk voices
147
+ mk dub a.mp4 --srt work/a/subs.srt --out work/dub.mp4 --voice Huihui --mix-original
148
+
149
+ # cut
150
+ mk edit work/plan.json --out work/final.mp4
151
+ mk auto --music bgm.mp3 --src footage --out work/mv.mp4 --transition fade
152
+ ```
153
+
154
+ Every command accepts `--json`. Without it you get a short human summary.
155
+
156
+ ### `mk auto` — beat-synced montage
157
+
158
+ Analyzes the track, decides how many beats per cut per section (quiet sections
159
+ get longer cuts, loud ones shorter), picks shots from a folder, snaps cuts to
160
+ beats and renders `xfade` transitions with matching `acrossfade` audio.
161
+
162
+ ```bash
163
+ mk auto --music bgm.mp3 --src footage --out mv.mp4 \
164
+ --size 1080x1920 --fit crop --transition fade --seed 7
165
+ mk auto --music bgm.mp3 --src footage --out mv.mp4 --plan-only # plan only
166
+ ```
167
+
168
+ ## MCP server
169
+
170
+ ```json
171
+ {
172
+ "mcpServers": {
173
+ "mediakit": { "command": "mediakit-mcp" }
174
+ }
175
+ }
176
+ ```
177
+
178
+ 12 tools: `probe`, `shots`, `music`, `subs`, `ocr`, `shotcard`, `index`,
179
+ `search`, `lyrics`, `dub`, `edit`, `auto`.
180
+
181
+ ## Measured, not assumed
182
+
183
+ Numbers below were produced on a local machine (CPU) with the benchmark
184
+ scripts in `tools/`. They are small-sample results, not leaderboard claims.
185
+
186
+ | Area | Result |
187
+ |---|---|
188
+ | Shot detection | 3 hard cuts detected at exactly 4.00s / 8.00s |
189
+ | Subtitles | 16.5s Chinese speech → 9 lines, traditional→simplified, width capped |
190
+ | Karaoke | `\kf` per word; at 0.2s 65% of subtitle pixels still unsung color |
191
+ | OCR | read burned subtitles back as 「大家晚上好。」and merged into SRT |
192
+ | Retrieval (synthetic, 8 segments) | recall@1 75% descriptive / 88% short, recall@3 100% |
193
+ | Retrieval (real footage, 8 clips) | recall@1 75%, recall@3 100% |
194
+ | Lyric CER vs reference subs | mix 89.7% → vocals 60.3% (small) → **54.4% (medium)** |
195
+ | Tempo correction | librosa default 103.36 BPM was a 4:3 artifact; tempogram prior → 80.75 BPM |
196
+ | Montage | 7 segments from a 20s track; 18.50s with 6×0.25s fades |
197
+ | Audio crossfade | 3×2s clips + 0.25s fade + keep_audio → 5.50s, audio kept |
198
+ | Dubbing | 9 lines → 18.60s output, full length, 2ch/48kHz |
199
+
200
+ ## Known limits
201
+
202
+ - Retrieval benchmarks are small (8 segments/clips) and CLIP is
203
+ phrasing-sensitive; low-information frames (pure white/black) fail.
204
+ - Singing transcription is still hard: 54% CER is the good case.
205
+ - `dub` uses Windows SAPI — robotic, and long lines are time-compressed at most 2×.
206
+ - VLM shot descriptions were validated on a handful of frames.
207
+ - `beat_this` and librosa often disagree by a few BPM; the package now anchors
208
+ tempo with a tempogram prior but does not prove which tracker is musically right.
209
+ - Transition handling assumes hard cuts when detecting shots.
210
+
211
+ ## Layout
212
+
213
+ ```
214
+ mediakit_cli/ package (17 modules + MCP server)
215
+ tools/ benchmarks: retrieval, lyrics CER, tempo
216
+ docs/ architecture and data contracts
217
+ examples/ sample edit plan
218
+ tests/ unit tests for pure logic
219
+ ```
220
+
221
+ ## Publishing
222
+
223
+ Releases go to PyPI from GitHub Actions with **Trusted Publishing** — no API
224
+ token is stored anywhere.
225
+
226
+ One-time setup on PyPI (project → Publishing → Add a publisher):
227
+
228
+ | Field | Value |
229
+ |---|---|
230
+ | Owner | `Lee2277-t` |
231
+ | Repository | `mediakit` |
232
+ | Workflow | `publish.yml` |
233
+ | Environment | `pypi` |
234
+
235
+ Then publish by pushing a tag that matches `pyproject.toml`:
236
+
237
+ ```bash
238
+ git tag v0.1.4
239
+ git push origin v0.1.4
240
+ ```
241
+
242
+ The workflow refuses to publish if the tag and the package version disagree.
243
+
244
+ ## License
245
+
246
+ MIT