mediakit-cli 0.1.2__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.2/LICENSE +21 -0
  2. mediakit_cli-0.1.2/PKG-INFO +221 -0
  3. mediakit_cli-0.1.2/README.md +162 -0
  4. mediakit_cli-0.1.2/mediakit_cli/__init__.py +5 -0
  5. mediakit_cli-0.1.2/mediakit_cli/__main__.py +4 -0
  6. mediakit_cli-0.1.2/mediakit_cli/auto.py +217 -0
  7. mediakit_cli-0.1.2/mediakit_cli/cli.py +665 -0
  8. mediakit_cli-0.1.2/mediakit_cli/config.py +68 -0
  9. mediakit_cli-0.1.2/mediakit_cli/dub.py +174 -0
  10. mediakit_cli-0.1.2/mediakit_cli/edit.py +280 -0
  11. mediakit_cli-0.1.2/mediakit_cli/index.py +101 -0
  12. mediakit_cli-0.1.2/mediakit_cli/lyrics.py +92 -0
  13. mediakit_cli-0.1.2/mediakit_cli/mcp_server.py +162 -0
  14. mediakit_cli-0.1.2/mediakit_cli/music.py +226 -0
  15. mediakit_cli-0.1.2/mediakit_cli/ocr.py +129 -0
  16. mediakit_cli-0.1.2/mediakit_cli/polish.py +85 -0
  17. mediakit_cli-0.1.2/mediakit_cli/probe.py +89 -0
  18. mediakit_cli-0.1.2/mediakit_cli/shotcard.py +133 -0
  19. mediakit_cli-0.1.2/mediakit_cli/shots.py +109 -0
  20. mediakit_cli-0.1.2/mediakit_cli/subs.py +349 -0
  21. mediakit_cli-0.1.2/mediakit_cli/util.py +111 -0
  22. mediakit_cli-0.1.2/mediakit_cli/vlm.py +88 -0
  23. mediakit_cli-0.1.2/mediakit_cli/watch.py +119 -0
  24. mediakit_cli-0.1.2/mediakit_cli.egg-info/PKG-INFO +221 -0
  25. mediakit_cli-0.1.2/mediakit_cli.egg-info/SOURCES.txt +33 -0
  26. mediakit_cli-0.1.2/mediakit_cli.egg-info/dependency_links.txt +1 -0
  27. mediakit_cli-0.1.2/mediakit_cli.egg-info/entry_points.txt +3 -0
  28. mediakit_cli-0.1.2/mediakit_cli.egg-info/requires.txt +57 -0
  29. mediakit_cli-0.1.2/mediakit_cli.egg-info/top_level.txt +1 -0
  30. mediakit_cli-0.1.2/pyproject.toml +75 -0
  31. mediakit_cli-0.1.2/setup.cfg +4 -0
  32. mediakit_cli-0.1.2/tests/test_auto.py +32 -0
  33. mediakit_cli-0.1.2/tests/test_config.py +29 -0
  34. mediakit_cli-0.1.2/tests/test_edit_math.py +28 -0
  35. mediakit_cli-0.1.2/tests/test_subs.py +44 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 mediakit contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,221 @@
1
+ Metadata-Version: 2.4
2
+ Name: mediakit-cli
3
+ Version: 0.1.2
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/your-name/mediakit
8
+ Keywords: video,subtitles,ffmpeg,whisper,agent,mcp
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Topic :: Multimedia :: Video
12
+ Classifier: Topic :: Multimedia :: Sound/Audio
13
+ Requires-Python: >=3.10
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: numpy>=1.24
17
+ Requires-Dist: pillow>=10
18
+ Requires-Dist: pysubs2>=1.6
19
+ Provides-Extra: asr
20
+ Requires-Dist: faster-whisper>=1.0; extra == "asr"
21
+ Provides-Extra: vision
22
+ Requires-Dist: opencv-python>=4.8; extra == "vision"
23
+ Requires-Dist: scenedetect>=0.6; extra == "vision"
24
+ Requires-Dist: rapidocr-onnxruntime>=1.3; extra == "vision"
25
+ Provides-Extra: timeline
26
+ Requires-Dist: opentimelineio>=0.16; extra == "timeline"
27
+ Provides-Extra: dl
28
+ Requires-Dist: yt-dlp>=2024.1.1; extra == "dl"
29
+ Provides-Extra: music
30
+ Requires-Dist: librosa>=0.10; extra == "music"
31
+ Requires-Dist: scipy>=1.10; extra == "music"
32
+ Requires-Dist: soundfile>=0.12; extra == "music"
33
+ Provides-Extra: separate
34
+ Requires-Dist: audio-separator>=0.20; extra == "separate"
35
+ Provides-Extra: search
36
+ Requires-Dist: open-clip-torch>=2.20; extra == "search"
37
+ Provides-Extra: mcp
38
+ Requires-Dist: mcp>=1.0; extra == "mcp"
39
+ Provides-Extra: windows
40
+ Requires-Dist: pywin32>=306; sys_platform == "win32" and extra == "windows"
41
+ Provides-Extra: all
42
+ Requires-Dist: faster-whisper>=1.0; extra == "all"
43
+ Requires-Dist: opencv-python>=4.8; extra == "all"
44
+ Requires-Dist: scenedetect>=0.6; extra == "all"
45
+ Requires-Dist: rapidocr-onnxruntime>=1.3; extra == "all"
46
+ Requires-Dist: opentimelineio>=0.16; extra == "all"
47
+ Requires-Dist: yt-dlp>=2024.1.1; extra == "all"
48
+ Requires-Dist: librosa>=0.10; extra == "all"
49
+ Requires-Dist: scipy>=1.10; extra == "all"
50
+ Requires-Dist: soundfile>=0.12; extra == "all"
51
+ Requires-Dist: audio-separator>=0.20; extra == "all"
52
+ Requires-Dist: open-clip-torch>=2.20; extra == "all"
53
+ Requires-Dist: mcp>=1.0; extra == "all"
54
+ Requires-Dist: pywin32>=306; sys_platform == "win32" and extra == "all"
55
+ Provides-Extra: dev
56
+ Requires-Dist: pytest>=7.4; extra == "dev"
57
+ Requires-Dist: ruff>=0.4; extra == "dev"
58
+ Dynamic: license-file
59
+
60
+ # mediakit
61
+
62
+ **One CLI, 17 commands, JSON out — for agents that need to watch, listen, subtitle and cut.**
63
+
64
+ `mediakit` is a thin orchestration layer over mature media tools. It does not
65
+ reimplement decoding, ASR or scene detection; it calls them and returns
66
+ structured results an agent can reason about, plus an MCP server so the whole
67
+ toolkit can be attached to any MCP client.
68
+
69
+ ```
70
+ $ mk watch clip.mp4 --out work/clip --lang zh --ocr
71
+ 语言 zh · 4 镜头 · 12 关键帧 · 转写 8 段 · 画面文字 2 条
72
+ $ mk search work/clip/index "穿黑裙子的女孩在草地上" --top 3
73
+ 42.50s score 0.311 ...
74
+ ```
75
+
76
+ [中文说明](README.zh-CN.md)
77
+
78
+ ## Why another wrapper?
79
+
80
+ Most tools are excellent at one step and then stop: PySceneDetect prints a
81
+ table, Whisper emits one long line, CLIP libraries return tensors. An agent
82
+ needs the opposite: short, composable commands with stable JSON, and no GUI.
83
+
84
+ | Upstream | What it does | What `mk` adds |
85
+ |---|---|---|
86
+ | PySceneDetect | shot boundaries | `contact.jpg`, `shots.json`, OTIO export |
87
+ | faster-whisper | segments + words | pause-based line breaking, width limits, 繁→简, karaoke, QA |
88
+ | ffmpeg | encode/cut/burn | one plan file, xfade + acrossfade, subtitle rescaling |
89
+ | RapidOCR | text boxes | frame sampling, de-dup, SRT output |
90
+ | CLIP | embeddings | index/search commands with thumbnails |
91
+ | librosa | tempo/beats | tempogram tempo prior, sections, chords, melody |
92
+ | VideoCaptioner | LLM subtitle polish | one command, local Ollama, bilingual output |
93
+
94
+ ## Install
95
+
96
+ ```bash
97
+ pip install "mediakit-cli[all]" # everything
98
+ pip install mediakit-cli # core only: probe, edit, auto, plan logic
99
+ ```
100
+
101
+ `ffmpeg` must be on `PATH` (or set `MEDIAKIT_FFMPEG`). Optional groups:
102
+
103
+ The distribution is named `mediakit-cli`; the Python import package is
104
+ `mediakit_cli` (to avoid a collision with the unrelated PyPI package
105
+ `mediakit`). The CLI command is `mk` either way.
106
+
107
+ | Extra | Enables | Install |
108
+ |---|---|---|
109
+ | `asr` | `subs`, `watch`, `lyrics` | `faster-whisper` |
110
+ | `vision` | `shots`, `shotcard`, `ocr` | OpenCV, PySceneDetect, RapidOCR |
111
+ | `music` | `music` | librosa |
112
+ | `search` | `index`, `search` | open_clip + ViT-B-32 weights |
113
+ | `separate` | `lyrics --separate` | audio-separator |
114
+ | `mcp` | `mediakit-mcp` | MCP SDK |
115
+ | `windows` | `dub`, `voices` | pywin32 + SAPI |
116
+ | `timeline` | `shots --otio` | OpenTimelineIO |
117
+
118
+ Environment overrides: `MEDIAKIT_FFMPEG`, `MEDIAKIT_AUDIO_SEPARATOR`,
119
+ `MEDIAKIT_VIDEOCAPTIONER`, `MEDIAKIT_OLLAMA_BASE`, `MEDIAKIT_VLM_MODEL`.
120
+
121
+ ## Commands
122
+
123
+ ```bash
124
+ # look
125
+ mk probe a.mp4
126
+ mk watch a.mp4 --out work/a --lang zh --ocr
127
+ mk frames a.mp4 --n 12 --out work/a/frames
128
+ mk ocr a.mp4 --out work/a/ocr --every 2
129
+ mk index a.mp4 --out work/a/index
130
+ mk search work/a/index "a girl running on grass"
131
+
132
+ # listen
133
+ mk music song.mp3 --chords --melody --engine beat-this
134
+ mk lyrics song.mp3 --out work/lyrics --lang ja
135
+
136
+ # dissect
137
+ mk shots a.mp4 --out work/a --otio
138
+ mk shotcard a.mp4 --out work/a/card --vlm
139
+
140
+ # subtitle
141
+ mk subs a.mp4 --lang zh --out work/a --size 1080x1920 --max-chars 12 --karaoke --qa
142
+ mk subqa work/a/subs.srt
143
+ mk polish work/a/subs.srt --out work/a/polished.srt
144
+ mk voices
145
+ mk dub a.mp4 --srt work/a/subs.srt --out work/dub.mp4 --voice Huihui --mix-original
146
+
147
+ # cut
148
+ mk edit work/plan.json --out work/final.mp4
149
+ mk auto --music bgm.mp3 --src footage --out work/mv.mp4 --transition fade
150
+ ```
151
+
152
+ Every command accepts `--json`. Without it you get a short human summary.
153
+
154
+ ### `mk auto` — beat-synced montage
155
+
156
+ Analyzes the track, decides how many beats per cut per section (quiet sections
157
+ get longer cuts, loud ones shorter), picks shots from a folder, snaps cuts to
158
+ beats and renders `xfade` transitions with matching `acrossfade` audio.
159
+
160
+ ```bash
161
+ mk auto --music bgm.mp3 --src footage --out mv.mp4 \
162
+ --size 1080x1920 --fit crop --transition fade --seed 7
163
+ mk auto --music bgm.mp3 --src footage --out mv.mp4 --plan-only # plan only
164
+ ```
165
+
166
+ ## MCP server
167
+
168
+ ```json
169
+ {
170
+ "mcpServers": {
171
+ "mediakit": { "command": "mediakit-mcp" }
172
+ }
173
+ }
174
+ ```
175
+
176
+ 12 tools: `probe`, `shots`, `music`, `subs`, `ocr`, `shotcard`, `index`,
177
+ `search`, `lyrics`, `dub`, `edit`, `auto`.
178
+
179
+ ## Measured, not assumed
180
+
181
+ Numbers below were produced on a local machine (CPU) with the benchmark
182
+ scripts in `tools/`. They are small-sample results, not leaderboard claims.
183
+
184
+ | Area | Result |
185
+ |---|---|
186
+ | Shot detection | 3 hard cuts detected at exactly 4.00s / 8.00s |
187
+ | Subtitles | 16.5s Chinese speech → 9 lines, traditional→simplified, width capped |
188
+ | Karaoke | `\kf` per word; at 0.2s 65% of subtitle pixels still unsung color |
189
+ | OCR | read burned subtitles back as 「大家晚上好。」and merged into SRT |
190
+ | Retrieval (synthetic, 8 segments) | recall@1 75% descriptive / 88% short, recall@3 100% |
191
+ | Retrieval (real footage, 8 clips) | recall@1 75%, recall@3 100% |
192
+ | Lyric CER vs reference subs | mix 89.7% → vocals 60.3% (small) → **54.4% (medium)** |
193
+ | Tempo correction | librosa default 103.36 BPM was a 4:3 artifact; tempogram prior → 80.75 BPM |
194
+ | Montage | 7 segments from a 20s track; 18.50s with 6×0.25s fades |
195
+ | Audio crossfade | 3×2s clips + 0.25s fade + keep_audio → 5.50s, audio kept |
196
+ | Dubbing | 9 lines → 18.60s output, full length, 2ch/48kHz |
197
+
198
+ ## Known limits
199
+
200
+ - Retrieval benchmarks are small (8 segments/clips) and CLIP is
201
+ phrasing-sensitive; low-information frames (pure white/black) fail.
202
+ - Singing transcription is still hard: 54% CER is the good case.
203
+ - `dub` uses Windows SAPI — robotic, and long lines are time-compressed at most 2×.
204
+ - VLM shot descriptions were validated on a handful of frames.
205
+ - `beat_this` and librosa often disagree by a few BPM; the package now anchors
206
+ tempo with a tempogram prior but does not prove which tracker is musically right.
207
+ - Transition handling assumes hard cuts when detecting shots.
208
+
209
+ ## Layout
210
+
211
+ ```
212
+ mediakit_cli/ package (17 modules + MCP server)
213
+ tools/ benchmarks: retrieval, lyrics CER, tempo
214
+ docs/ architecture and data contracts
215
+ examples/ sample edit plan
216
+ tests/ unit tests for pure logic
217
+ ```
218
+
219
+ ## License
220
+
221
+ MIT
@@ -0,0 +1,162 @@
1
+ # mediakit
2
+
3
+ **One CLI, 17 commands, JSON out — for agents that need to watch, listen, subtitle and cut.**
4
+
5
+ `mediakit` is a thin orchestration layer over mature media tools. It does not
6
+ reimplement decoding, ASR or scene detection; it calls them and returns
7
+ structured results an agent can reason about, plus an MCP server so the whole
8
+ toolkit can be attached to any MCP client.
9
+
10
+ ```
11
+ $ mk watch clip.mp4 --out work/clip --lang zh --ocr
12
+ 语言 zh · 4 镜头 · 12 关键帧 · 转写 8 段 · 画面文字 2 条
13
+ $ mk search work/clip/index "穿黑裙子的女孩在草地上" --top 3
14
+ 42.50s score 0.311 ...
15
+ ```
16
+
17
+ [中文说明](README.zh-CN.md)
18
+
19
+ ## Why another wrapper?
20
+
21
+ Most tools are excellent at one step and then stop: PySceneDetect prints a
22
+ table, Whisper emits one long line, CLIP libraries return tensors. An agent
23
+ needs the opposite: short, composable commands with stable JSON, and no GUI.
24
+
25
+ | Upstream | What it does | What `mk` adds |
26
+ |---|---|---|
27
+ | PySceneDetect | shot boundaries | `contact.jpg`, `shots.json`, OTIO export |
28
+ | faster-whisper | segments + words | pause-based line breaking, width limits, 繁→简, karaoke, QA |
29
+ | ffmpeg | encode/cut/burn | one plan file, xfade + acrossfade, subtitle rescaling |
30
+ | RapidOCR | text boxes | frame sampling, de-dup, SRT output |
31
+ | CLIP | embeddings | index/search commands with thumbnails |
32
+ | librosa | tempo/beats | tempogram tempo prior, sections, chords, melody |
33
+ | VideoCaptioner | LLM subtitle polish | one command, local Ollama, bilingual output |
34
+
35
+ ## Install
36
+
37
+ ```bash
38
+ pip install "mediakit-cli[all]" # everything
39
+ pip install mediakit-cli # core only: probe, edit, auto, plan logic
40
+ ```
41
+
42
+ `ffmpeg` must be on `PATH` (or set `MEDIAKIT_FFMPEG`). Optional groups:
43
+
44
+ The distribution is named `mediakit-cli`; the Python import package is
45
+ `mediakit_cli` (to avoid a collision with the unrelated PyPI package
46
+ `mediakit`). The CLI command is `mk` either way.
47
+
48
+ | Extra | Enables | Install |
49
+ |---|---|---|
50
+ | `asr` | `subs`, `watch`, `lyrics` | `faster-whisper` |
51
+ | `vision` | `shots`, `shotcard`, `ocr` | OpenCV, PySceneDetect, RapidOCR |
52
+ | `music` | `music` | librosa |
53
+ | `search` | `index`, `search` | open_clip + ViT-B-32 weights |
54
+ | `separate` | `lyrics --separate` | audio-separator |
55
+ | `mcp` | `mediakit-mcp` | MCP SDK |
56
+ | `windows` | `dub`, `voices` | pywin32 + SAPI |
57
+ | `timeline` | `shots --otio` | OpenTimelineIO |
58
+
59
+ Environment overrides: `MEDIAKIT_FFMPEG`, `MEDIAKIT_AUDIO_SEPARATOR`,
60
+ `MEDIAKIT_VIDEOCAPTIONER`, `MEDIAKIT_OLLAMA_BASE`, `MEDIAKIT_VLM_MODEL`.
61
+
62
+ ## Commands
63
+
64
+ ```bash
65
+ # look
66
+ mk probe a.mp4
67
+ mk watch a.mp4 --out work/a --lang zh --ocr
68
+ mk frames a.mp4 --n 12 --out work/a/frames
69
+ mk ocr a.mp4 --out work/a/ocr --every 2
70
+ mk index a.mp4 --out work/a/index
71
+ mk search work/a/index "a girl running on grass"
72
+
73
+ # listen
74
+ mk music song.mp3 --chords --melody --engine beat-this
75
+ mk lyrics song.mp3 --out work/lyrics --lang ja
76
+
77
+ # dissect
78
+ mk shots a.mp4 --out work/a --otio
79
+ mk shotcard a.mp4 --out work/a/card --vlm
80
+
81
+ # subtitle
82
+ mk subs a.mp4 --lang zh --out work/a --size 1080x1920 --max-chars 12 --karaoke --qa
83
+ mk subqa work/a/subs.srt
84
+ mk polish work/a/subs.srt --out work/a/polished.srt
85
+ mk voices
86
+ mk dub a.mp4 --srt work/a/subs.srt --out work/dub.mp4 --voice Huihui --mix-original
87
+
88
+ # cut
89
+ mk edit work/plan.json --out work/final.mp4
90
+ mk auto --music bgm.mp3 --src footage --out work/mv.mp4 --transition fade
91
+ ```
92
+
93
+ Every command accepts `--json`. Without it you get a short human summary.
94
+
95
+ ### `mk auto` — beat-synced montage
96
+
97
+ Analyzes the track, decides how many beats per cut per section (quiet sections
98
+ get longer cuts, loud ones shorter), picks shots from a folder, snaps cuts to
99
+ beats and renders `xfade` transitions with matching `acrossfade` audio.
100
+
101
+ ```bash
102
+ mk auto --music bgm.mp3 --src footage --out mv.mp4 \
103
+ --size 1080x1920 --fit crop --transition fade --seed 7
104
+ mk auto --music bgm.mp3 --src footage --out mv.mp4 --plan-only # plan only
105
+ ```
106
+
107
+ ## MCP server
108
+
109
+ ```json
110
+ {
111
+ "mcpServers": {
112
+ "mediakit": { "command": "mediakit-mcp" }
113
+ }
114
+ }
115
+ ```
116
+
117
+ 12 tools: `probe`, `shots`, `music`, `subs`, `ocr`, `shotcard`, `index`,
118
+ `search`, `lyrics`, `dub`, `edit`, `auto`.
119
+
120
+ ## Measured, not assumed
121
+
122
+ Numbers below were produced on a local machine (CPU) with the benchmark
123
+ scripts in `tools/`. They are small-sample results, not leaderboard claims.
124
+
125
+ | Area | Result |
126
+ |---|---|
127
+ | Shot detection | 3 hard cuts detected at exactly 4.00s / 8.00s |
128
+ | Subtitles | 16.5s Chinese speech → 9 lines, traditional→simplified, width capped |
129
+ | Karaoke | `\kf` per word; at 0.2s 65% of subtitle pixels still unsung color |
130
+ | OCR | read burned subtitles back as 「大家晚上好。」and merged into SRT |
131
+ | Retrieval (synthetic, 8 segments) | recall@1 75% descriptive / 88% short, recall@3 100% |
132
+ | Retrieval (real footage, 8 clips) | recall@1 75%, recall@3 100% |
133
+ | Lyric CER vs reference subs | mix 89.7% → vocals 60.3% (small) → **54.4% (medium)** |
134
+ | Tempo correction | librosa default 103.36 BPM was a 4:3 artifact; tempogram prior → 80.75 BPM |
135
+ | Montage | 7 segments from a 20s track; 18.50s with 6×0.25s fades |
136
+ | Audio crossfade | 3×2s clips + 0.25s fade + keep_audio → 5.50s, audio kept |
137
+ | Dubbing | 9 lines → 18.60s output, full length, 2ch/48kHz |
138
+
139
+ ## Known limits
140
+
141
+ - Retrieval benchmarks are small (8 segments/clips) and CLIP is
142
+ phrasing-sensitive; low-information frames (pure white/black) fail.
143
+ - Singing transcription is still hard: 54% CER is the good case.
144
+ - `dub` uses Windows SAPI — robotic, and long lines are time-compressed at most 2×.
145
+ - VLM shot descriptions were validated on a handful of frames.
146
+ - `beat_this` and librosa often disagree by a few BPM; the package now anchors
147
+ tempo with a tempogram prior but does not prove which tracker is musically right.
148
+ - Transition handling assumes hard cuts when detecting shots.
149
+
150
+ ## Layout
151
+
152
+ ```
153
+ mediakit_cli/ package (17 modules + MCP server)
154
+ tools/ benchmarks: retrieval, lyrics CER, tempo
155
+ docs/ architecture and data contracts
156
+ examples/ sample edit plan
157
+ tests/ unit tests for pure logic
158
+ ```
159
+
160
+ ## License
161
+
162
+ MIT
@@ -0,0 +1,5 @@
1
+ """mediakit — agent-friendly video/audio analysis and editing toolkit."""
2
+
3
+ __version__ = "0.1.2"
4
+
5
+ __all__ = ["__version__"]
@@ -0,0 +1,4 @@
1
+ from .cli import main
2
+
3
+ if __name__ == "__main__":
4
+ raise SystemExit(main())
@@ -0,0 +1,217 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import random
5
+ from pathlib import Path
6
+
7
+ from .edit import render
8
+ from .music import analyze
9
+ from .util import ensure_dir, media_path
10
+
11
+ VIDEO_EXT = {".mp4", ".mov", ".mkv", ".webm", ".avi", ".m4v"}
12
+
13
+
14
+ def collect_sources(srcs) -> list:
15
+ files = []
16
+ for raw in srcs:
17
+ p = Path(raw).expanduser()
18
+ if p.is_dir():
19
+ files += [f for f in sorted(p.rglob("*")) if f.suffix.lower() in VIDEO_EXT]
20
+ elif p.suffix.lower() in VIDEO_EXT:
21
+ files.append(media_path(p))
22
+ # 去重且保持顺序
23
+ seen, out = set(), []
24
+ for f in files:
25
+ key = str(f.resolve()).lower()
26
+ if key not in seen:
27
+ seen.add(key)
28
+ out.append(f.resolve())
29
+ return out
30
+
31
+
32
+ def pace_map(sections: list, default_k: int = 4, k_fast: int = 3, k_slow: int = 8) -> list:
33
+ """按段落能量定每段的“几拍一切”:能量越高切得越密。
34
+
35
+ 能量差小于 15% 时视为同一档,避免两段几乎一样响却切出 6 拍 vs 2 拍。
36
+ """
37
+ if not sections or len(sections) < 2:
38
+ return []
39
+ energies = [float(s.get("energy") or 0) for s in sections]
40
+ lo, hi = min(energies), max(energies)
41
+ spread = (hi - lo) / max(hi, 1e-9)
42
+ uniform = spread < 0.15
43
+ out = []
44
+ for s, e in zip(sections, energies):
45
+ if uniform:
46
+ k = default_k
47
+ else:
48
+ norm = (e - lo) / (hi - lo) if hi > lo else 0.5
49
+ k = int(round(k_slow + (k_fast - k_slow) * norm))
50
+ out.append(
51
+ {
52
+ "start": s["start"],
53
+ "end": s["end"],
54
+ "energy": e,
55
+ "beats_per_cut": max(1, min(k, k_slow)),
56
+ }
57
+ )
58
+ return out
59
+
60
+
61
+ def cut_points(
62
+ beats: list,
63
+ duration: float,
64
+ beats_per_cut: int,
65
+ pmap: list | None = None,
66
+ fallback: float = 2.5,
67
+ ) -> list:
68
+ if not beats:
69
+ n = max(1, int(duration // fallback))
70
+ return [round(i * fallback, 3) for i in range(n + 1)] + [round(duration, 3)]
71
+ cuts = [0.0]
72
+ if pmap:
73
+ for sec in pmap:
74
+ k = int(sec["beats_per_cut"])
75
+ bs = [b for b in beats if sec["start"] <= b < sec["end"]]
76
+ for i, b in enumerate(bs):
77
+ if (i + 1) % k == 0 and b > cuts[-1] + 0.4 and b < duration - 0.4:
78
+ cuts.append(round(b, 3))
79
+ else:
80
+ for i, b in enumerate(beats):
81
+ if (i + 1) % max(1, beats_per_cut) == 0 and b > cuts[-1] + 0.4 and b < duration - 0.4:
82
+ cuts.append(round(b, 3))
83
+ cuts.append(round(duration, 3))
84
+ return cuts
85
+
86
+
87
+ def build_pool(files: list, limit: int, min_shot: float, progress) -> list:
88
+ from .shots import detect_shots
89
+
90
+ pool = []
91
+ for idx, f in enumerate(files[:limit], 1):
92
+ try:
93
+ shots = detect_shots(f)
94
+ except Exception as exc:
95
+ progress(f"跳过 {f.name}: {exc}")
96
+ continue
97
+ kept = [s for s in shots if s["dur"] >= min_shot]
98
+ progress(f"[{idx}/{min(len(files), limit)}] {f.name}: {len(shots)} 镜头,{len(kept)} 个可用")
99
+ for s in kept:
100
+ pool.append({"src": str(f), "start": s["start"], "end": s["end"], "dur": s["dur"]})
101
+ return pool
102
+
103
+
104
+ def select_clips(cuts: list, pool: list, seed: int, progress) -> tuple:
105
+ if not pool:
106
+ raise RuntimeError("素材里没有可用镜头:检查 --src 路径或降低 --min-shot")
107
+ rng = random.Random(seed)
108
+ clips, used, last_key = [], set(), None
109
+ clamped, reused = 0, 0
110
+ cursor = 0.0
111
+ for cut in cuts[1:]:
112
+ need = cut - cursor
113
+ if need < 0.4:
114
+ continue
115
+ cands = [s for s in pool if s["dur"] >= need - 1e-3]
116
+ if not cands:
117
+ cands = [max(pool, key=lambda s: s["dur"])]
118
+ clamped += 1
119
+ fresh = [s for s in cands if (s["src"], s["start"]) not in used]
120
+ avoid_last = [s for s in (fresh or cands) if (s["src"], s["start"]) != last_key]
121
+ pick_pool = avoid_last or fresh or cands
122
+ shot = rng.choice(pick_pool)
123
+ if shot["dur"] < need:
124
+ need = shot["dur"]
125
+ key = (shot["src"], shot["start"])
126
+ if key in used:
127
+ reused += 1
128
+ used.add(key)
129
+ last_key = key
130
+ hi = max(shot["start"], shot["end"] - need)
131
+ in_t = rng.uniform(shot["start"], hi)
132
+ clips.append(
133
+ {
134
+ "src": shot["src"],
135
+ "in": round(in_t, 3),
136
+ "out": round(in_t + need, 3),
137
+ }
138
+ )
139
+ cursor += need
140
+ progress(f"选了 {len(clips)} 段,复用 {reused} 次,素材不够被压短 {clamped} 次")
141
+ return clips, {"reused": reused, "clamped": clamped, "filled": round(cursor, 3)}
142
+
143
+
144
+ def generate(
145
+ music,
146
+ srcs,
147
+ out,
148
+ size=(1080, 1920),
149
+ fps: int = 30,
150
+ fit: str = "crop",
151
+ beats_per_cut: int = 4,
152
+ pace: str = "auto",
153
+ transition: str = "none",
154
+ transition_duration: float = 0.25,
155
+ max_sources: int = 12,
156
+ min_shot: float = 0.8,
157
+ seed: int = 7,
158
+ gain_db: float = -14.0,
159
+ plan_only: bool = False,
160
+ progress=None,
161
+ ) -> dict:
162
+ note = progress or (lambda *_: None)
163
+ m_path = media_path(music)
164
+ note(f"分析音乐 {m_path.name}")
165
+ m = analyze(m_path, with_beats=True)
166
+ pmap = pace_map(m.get("sections") or [], default_k=beats_per_cut) if pace == "auto" else []
167
+ cuts = cut_points(m["beats"], m["duration"], beats_per_cut, pmap=pmap)
168
+ if pace == "auto" and len(cuts) < 3:
169
+ cuts = cut_points(m["beats"], m["duration"], beats_per_cut)
170
+ pmap = []
171
+ note("段落变化不足,退回固定拍数")
172
+ note(f"{m['tempo_bpm']} BPM,{len(m['beats'])} 拍,切点 {len(cuts) - 1} 个,节奏 {pace}")
173
+
174
+ files = collect_sources(srcs)
175
+ note(f"素材 {len(files)} 个文件,本次扫描前 {min(len(files), max_sources)} 个")
176
+ pool = build_pool(files, max_sources, min_shot, note)
177
+ clips, stats = select_clips(cuts, pool, seed, note)
178
+
179
+ plan = {
180
+ "size": list(size),
181
+ "fps": fps,
182
+ "fit": fit,
183
+ "crf": 20,
184
+ "clips": clips,
185
+ "music": {"src": str(m_path), "gain_db": gain_db, "loop": True},
186
+ "keep_audio": False,
187
+ }
188
+ if transition and transition != "none":
189
+ plan["transition"] = {"type": transition, "duration": transition_duration}
190
+ out_path = Path(out).resolve()
191
+ ensure_dir(out_path.parent)
192
+ plan_path = out_path.with_suffix(out_path.suffix + ".plan.json")
193
+ plan_path.write_text(json.dumps(plan, ensure_ascii=False, indent=2), encoding="utf-8")
194
+ note(f"计划已写入 {plan_path}")
195
+
196
+ result = {
197
+ "out": None,
198
+ "plan": str(plan_path),
199
+ "duration": m["duration"],
200
+ "tempo_bpm": m["tempo_bpm"],
201
+ "beats": len(m["beats"]),
202
+ "cuts": cuts,
203
+ "segments": len(clips),
204
+ "sources": len(files),
205
+ "pool_shots": len(pool),
206
+ "seed": seed,
207
+ "stats": stats,
208
+ "pace": {"mode": pace, "sections": pmap},
209
+ "transition": transition if transition != "none" else None,
210
+ }
211
+ if plan_only:
212
+ return result
213
+
214
+ note("开始渲染")
215
+ rendered = render(plan, out_path)
216
+ result.update({"out": rendered["out"], "duration": rendered["duration"]})
217
+ return result