reachreel 0.3.0__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.
- reachreel-0.3.0/.githooks/commit-msg +11 -0
- reachreel-0.3.0/.github/workflows/ci.yml +99 -0
- reachreel-0.3.0/.gitignore +30 -0
- reachreel-0.3.0/.pre-commit-config.yaml +40 -0
- reachreel-0.3.0/AGENTS.md +155 -0
- reachreel-0.3.0/CHANGELOG.md +123 -0
- reachreel-0.3.0/CHANGELOG.zh-CN.md +124 -0
- reachreel-0.3.0/LICENSE +201 -0
- reachreel-0.3.0/NOTICE +5 -0
- reachreel-0.3.0/PKG-INFO +218 -0
- reachreel-0.3.0/README.md +183 -0
- reachreel-0.3.0/README.zh-CN.md +185 -0
- reachreel-0.3.0/config.example.toml +114 -0
- reachreel-0.3.0/docs/GLOSSARY.md +131 -0
- reachreel-0.3.0/docs/README.md +82 -0
- reachreel-0.3.0/docs/en/BGM.md +89 -0
- reachreel-0.3.0/docs/en/CONFIGURATION.md +440 -0
- reachreel-0.3.0/docs/en/DESKTOP_ARCHITECTURE.md +583 -0
- reachreel-0.3.0/docs/en/DEVELOPMENT.md +890 -0
- reachreel-0.3.0/docs/en/LANGUAGES.md +119 -0
- reachreel-0.3.0/docs/en/LOCALIZATION.md +393 -0
- reachreel-0.3.0/docs/en/ROADMAP.md +377 -0
- reachreel-0.3.0/docs/en/USER_GUIDE.md +804 -0
- reachreel-0.3.0/docs/zh-CN/BGM.md +89 -0
- reachreel-0.3.0/docs/zh-CN/CONFIGURATION.md +440 -0
- reachreel-0.3.0/docs/zh-CN/DESKTOP_ARCHITECTURE.md +583 -0
- reachreel-0.3.0/docs/zh-CN/DEVELOPMENT.md +890 -0
- reachreel-0.3.0/docs/zh-CN/LANGUAGES.md +106 -0
- reachreel-0.3.0/docs/zh-CN/LOCALIZATION.md +393 -0
- reachreel-0.3.0/docs/zh-CN/ROADMAP.md +377 -0
- reachreel-0.3.0/docs/zh-CN/USER_GUIDE.md +804 -0
- reachreel-0.3.0/pyproject.toml +80 -0
- reachreel-0.3.0/requirements.txt +4 -0
- reachreel-0.3.0/scripts/__init__.py +0 -0
- reachreel-0.3.0/scripts/apdev_charset.json +8 -0
- reachreel-0.3.0/scripts/check_changelog.py +182 -0
- reachreel-0.3.0/scripts/check_commit_messages.py +171 -0
- reachreel-0.3.0/scripts/check_config_docs.py +168 -0
- reachreel-0.3.0/src/reachreel/__init__.py +3 -0
- reachreel-0.3.0/src/reachreel/__main__.py +4 -0
- reachreel-0.3.0/src/reachreel/cli/__init__.py +0 -0
- reachreel-0.3.0/src/reachreel/cli/main.py +607 -0
- reachreel-0.3.0/src/reachreel/core/__init__.py +0 -0
- reachreel-0.3.0/src/reachreel/core/cache.py +101 -0
- reachreel-0.3.0/src/reachreel/core/config.py +231 -0
- reachreel-0.3.0/src/reachreel/core/util.py +216 -0
- reachreel-0.3.0/src/reachreel/domain/__init__.py +0 -0
- reachreel-0.3.0/src/reachreel/domain/models.py +111 -0
- reachreel-0.3.0/src/reachreel/domain/timeline.py +192 -0
- reachreel-0.3.0/src/reachreel/engines/__init__.py +0 -0
- reachreel-0.3.0/src/reachreel/engines/tts.py +375 -0
- reachreel-0.3.0/src/reachreel/engines/vlm.py +348 -0
- reachreel-0.3.0/src/reachreel/generation/__init__.py +0 -0
- reachreel-0.3.0/src/reachreel/generation/script.py +311 -0
- reachreel-0.3.0/src/reachreel/i18n/__init__.py +100 -0
- reachreel-0.3.0/src/reachreel/languages.py +285 -0
- reachreel-0.3.0/src/reachreel/locales/en.toml +249 -0
- reachreel-0.3.0/src/reachreel/locales/zh-CN.toml +249 -0
- reachreel-0.3.0/src/reachreel/media/__init__.py +0 -0
- reachreel-0.3.0/src/reachreel/media/audio.py +308 -0
- reachreel-0.3.0/src/reachreel/media/render.py +230 -0
- reachreel-0.3.0/src/reachreel/media/scenes.py +338 -0
- reachreel-0.3.0/src/reachreel/media/subtitles.py +523 -0
- reachreel-0.3.0/src/reachreel/pipeline/__init__.py +0 -0
- reachreel-0.3.0/src/reachreel/pipeline/orchestrator.py +1114 -0
- reachreel-0.3.0/src/reachreel/pipeline/qa.py +1192 -0
- reachreel-0.3.0/src/reachreel/prompts/__init__.py +72 -0
- reachreel-0.3.0/src/reachreel/prompts/en/messages.toml +27 -0
- reachreel-0.3.0/src/reachreel/prompts/en/script.txt +21 -0
- reachreel-0.3.0/src/reachreel/prompts/en/style.txt +1 -0
- reachreel-0.3.0/src/reachreel/prompts/en/vlm.txt +13 -0
- reachreel-0.3.0/src/reachreel/prompts/zh/messages.toml +27 -0
- reachreel-0.3.0/src/reachreel/prompts/zh/script.txt +21 -0
- reachreel-0.3.0/src/reachreel/prompts/zh/style.txt +1 -0
- reachreel-0.3.0/src/reachreel/prompts/zh/vlm.txt +13 -0
- reachreel-0.3.0/tests/__init__.py +0 -0
- reachreel-0.3.0/tests/fixtures/README.md +19 -0
- reachreel-0.3.0/tests/integration/__init__.py +0 -0
- reachreel-0.3.0/tests/integration/test_scenes.py +370 -0
- reachreel-0.3.0/tests/integration/test_smoke.py +439 -0
- reachreel-0.3.0/tests/integration/test_timeline.py +105 -0
- reachreel-0.3.0/tests/unit/__init__.py +0 -0
- reachreel-0.3.0/tests/unit/test_changelog_sync.py +133 -0
- reachreel-0.3.0/tests/unit/test_commit_messages.py +99 -0
- reachreel-0.3.0/tests/unit/test_config_docs.py +138 -0
- reachreel-0.3.0/tests/unit/test_i18n_prompts.py +95 -0
- reachreel-0.3.0/tests/unit/test_languages.py +124 -0
- reachreel-0.3.0/tests/unit/test_qa.py +287 -0
- reachreel-0.3.0/tests/unit/test_units.py +746 -0
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
#!/bin/sh
|
|
2
|
+
# Reject commit messages that break the Conventional Commits rule in AGENTS.md.
|
|
3
|
+
# Enable once per clone: git config core.hooksPath .githooks
|
|
4
|
+
#
|
|
5
|
+
# Never block a commit because the tooling itself is missing: a contributor
|
|
6
|
+
# without python3 still gets their commit through, with a warning.
|
|
7
|
+
if ! command -v python3 >/dev/null 2>&1; then
|
|
8
|
+
echo "reachreel: python3 not found, skipping the commit message check" >&2
|
|
9
|
+
exit 0
|
|
10
|
+
fi
|
|
11
|
+
exec python3 "$(git rev-parse --show-toplevel)/scripts/check_commit_messages.py" --file "$1"
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
concurrency:
|
|
9
|
+
group: ci-${{ github.ref }}
|
|
10
|
+
cancel-in-progress: true
|
|
11
|
+
|
|
12
|
+
jobs:
|
|
13
|
+
checks:
|
|
14
|
+
name: repo conventions
|
|
15
|
+
# Cheap checks on a cheap runner: they fail in seconds, before macOS
|
|
16
|
+
# minutes are spent, and a violation is not reported twice by the matrix.
|
|
17
|
+
runs-on: ubuntu-latest
|
|
18
|
+
steps:
|
|
19
|
+
- uses: actions/checkout@v4
|
|
20
|
+
with:
|
|
21
|
+
# Commit-message checks need the history this push or PR adds.
|
|
22
|
+
fetch-depth: 0
|
|
23
|
+
|
|
24
|
+
- uses: astral-sh/setup-uv@v5
|
|
25
|
+
|
|
26
|
+
- name: Commit messages
|
|
27
|
+
# Conventional Commits in English, as declared in AGENTS.md.
|
|
28
|
+
env:
|
|
29
|
+
EVENT_NAME: ${{ github.event_name }}
|
|
30
|
+
BASE_REF: ${{ github.base_ref }}
|
|
31
|
+
BEFORE_SHA: ${{ github.event.before }}
|
|
32
|
+
HEAD_SHA: ${{ github.sha }}
|
|
33
|
+
run: |
|
|
34
|
+
if [ "$EVENT_NAME" = "pull_request" ]; then
|
|
35
|
+
RANGE="origin/$BASE_REF..HEAD"
|
|
36
|
+
else
|
|
37
|
+
RANGE="$BEFORE_SHA..$HEAD_SHA"
|
|
38
|
+
fi
|
|
39
|
+
echo "Checking commit messages in $RANGE"
|
|
40
|
+
python3 scripts/check_commit_messages.py --range "$RANGE"
|
|
41
|
+
|
|
42
|
+
- name: Changelog parity
|
|
43
|
+
# Structure only; per-section bullet counts are a --strict release check.
|
|
44
|
+
run: python3 scripts/check_changelog.py
|
|
45
|
+
|
|
46
|
+
- name: Install apdev
|
|
47
|
+
# Shared APCore tooling: source charset and circular-import checks.
|
|
48
|
+
run: uv tool install 'apdev==0.2.5'
|
|
49
|
+
|
|
50
|
+
- name: Python sources are English
|
|
51
|
+
# scripts/apdev_charset.json allows CJK punctuation (parsing data) but
|
|
52
|
+
# keeps Chinese ideographs illegal outside locales/ and prompts/.
|
|
53
|
+
run: >-
|
|
54
|
+
apdev check-chars --charset-file scripts/apdev_charset.json
|
|
55
|
+
$(find src/reachreel -name '*.py')
|
|
56
|
+
|
|
57
|
+
- name: No circular imports
|
|
58
|
+
run: apdev check-imports
|
|
59
|
+
|
|
60
|
+
- name: Configuration surface
|
|
61
|
+
# Settings <-> config.example.toml <-> both CONFIGURATION.md files.
|
|
62
|
+
run: python3 scripts/check_config_docs.py
|
|
63
|
+
|
|
64
|
+
test:
|
|
65
|
+
name: lint + unit tests (Python ${{ matrix.python-version }})
|
|
66
|
+
# macOS 14 images are retired; macos-15 is the current arm64 (Apple silicon)
|
|
67
|
+
# label, which matches the MLX/`say` runtime this project targets.
|
|
68
|
+
runs-on: macos-15
|
|
69
|
+
strategy:
|
|
70
|
+
fail-fast: false
|
|
71
|
+
matrix:
|
|
72
|
+
python-version: ["3.11", "3.12"]
|
|
73
|
+
steps:
|
|
74
|
+
- uses: actions/checkout@v4
|
|
75
|
+
|
|
76
|
+
- uses: astral-sh/setup-uv@v5
|
|
77
|
+
with:
|
|
78
|
+
enable-cache: true
|
|
79
|
+
|
|
80
|
+
- name: Create virtual environment
|
|
81
|
+
run: uv venv --python ${{ matrix.python-version }}
|
|
82
|
+
|
|
83
|
+
- name: Install package without runtime model dependencies
|
|
84
|
+
# Unit tests do not need MLX, Whisper, or Kokoro; skipping runtime deps
|
|
85
|
+
# keeps CI fast and avoids multi-gigabyte model wheels.
|
|
86
|
+
run: uv pip install --python .venv/bin/python --no-deps -e .
|
|
87
|
+
|
|
88
|
+
- name: Install lightweight dependencies used by unit tests
|
|
89
|
+
run: uv pip install --python .venv/bin/python 'platformdirs>=4.0'
|
|
90
|
+
|
|
91
|
+
- name: Lint
|
|
92
|
+
run: uvx ruff@0.17.6 check src/reachreel tests scripts
|
|
93
|
+
|
|
94
|
+
- name: Unit tests
|
|
95
|
+
run: .venv/bin/python -m unittest discover -s tests -v
|
|
96
|
+
|
|
97
|
+
- name: Build package
|
|
98
|
+
if: matrix.python-version == '3.12'
|
|
99
|
+
run: uv build
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
.venv/
|
|
2
|
+
.envrc
|
|
3
|
+
__pycache__/
|
|
4
|
+
dist/
|
|
5
|
+
build/
|
|
6
|
+
*.pyc
|
|
7
|
+
*.pyo
|
|
8
|
+
.pytest_cache/
|
|
9
|
+
output/
|
|
10
|
+
|
|
11
|
+
# Local media: never commit source videos or renders.
|
|
12
|
+
*.mp4
|
|
13
|
+
*.mov
|
|
14
|
+
*.mkv
|
|
15
|
+
*.webm
|
|
16
|
+
*.m4v
|
|
17
|
+
*.avi
|
|
18
|
+
|
|
19
|
+
tests/fixtures/work*/
|
|
20
|
+
tests/fixtures/*.mp4
|
|
21
|
+
tests/fixtures/*.mp3
|
|
22
|
+
tests/fixtures/*.wav
|
|
23
|
+
tests/fixtures/*.aiff
|
|
24
|
+
tests/fixtures/list.txt
|
|
25
|
+
.DS_Store
|
|
26
|
+
*.egg-info/
|
|
27
|
+
.ruff_cache/
|
|
28
|
+
|
|
29
|
+
# Local inputs (BGM, fonts, models). Never commit.
|
|
30
|
+
inputs/
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Local hook stack. One-time setup per clone:
|
|
2
|
+
# uv pip install --python .venv/bin/python -e '.[dev]'
|
|
3
|
+
# pre-commit install # installs both hook types via default_install_hook_types
|
|
4
|
+
# git config --unset core.hooksPath # only if an older clone used .githooks
|
|
5
|
+
#
|
|
6
|
+
# Every hook mirrors a CI step in .github/workflows/ci.yml.
|
|
7
|
+
default_install_hook_types: [pre-commit, commit-msg]
|
|
8
|
+
|
|
9
|
+
repos:
|
|
10
|
+
- repo: local
|
|
11
|
+
hooks:
|
|
12
|
+
- id: apdev-check-imports
|
|
13
|
+
name: apdev check-imports
|
|
14
|
+
entry: apdev check-imports
|
|
15
|
+
language: python
|
|
16
|
+
additional_dependencies: ["apdev==0.2.5"]
|
|
17
|
+
pass_filenames: false
|
|
18
|
+
always_run: true
|
|
19
|
+
|
|
20
|
+
- id: apdev-check-chars
|
|
21
|
+
name: apdev check-chars (Python sources)
|
|
22
|
+
# ASCII + emoji + CJK punctuation; ideographs stay illegal. Test
|
|
23
|
+
# fixtures are excluded because they contain Chinese on purpose.
|
|
24
|
+
entry: apdev check-chars --charset-file scripts/apdev_charset.json
|
|
25
|
+
language: python
|
|
26
|
+
additional_dependencies: ["apdev==0.2.5"]
|
|
27
|
+
files: ^src/reachreel/.*\.py$
|
|
28
|
+
|
|
29
|
+
- id: commit-message
|
|
30
|
+
name: commit message format
|
|
31
|
+
entry: python3 scripts/check_commit_messages.py --file
|
|
32
|
+
language: system
|
|
33
|
+
stages: [commit-msg]
|
|
34
|
+
|
|
35
|
+
- repo: https://github.com/astral-sh/ruff-pre-commit
|
|
36
|
+
rev: v0.17.6
|
|
37
|
+
hooks:
|
|
38
|
+
- id: ruff
|
|
39
|
+
args: [--fix]
|
|
40
|
+
files: ^(src/reachreel|tests|scripts)/
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# AGENTS.md — ReachReel
|
|
2
|
+
|
|
3
|
+
This file is the working agreement for AI agents and contributors in this repository.
|
|
4
|
+
|
|
5
|
+
## Language policy (mandatory)
|
|
6
|
+
|
|
7
|
+
- All source code, identifiers, comments, docstrings, log messages, error messages, commit messages, and PR descriptions MUST be written in English.
|
|
8
|
+
- All documentation is bilingual: `README.md` (English) and `README.zh-CN.md` (Simplified Chinese); `docs/en/` and `docs/zh-CN/` hold the two language versions of every document.
|
|
9
|
+
- User documentation is Chinese-authoritative; engineering documentation is English-authoritative. Both versions must be kept in sync.
|
|
10
|
+
- Prompt content is data, not source code. Language-specific prompts live under `src/reachreel/prompts/<language>/`.
|
|
11
|
+
- Do not add Chinese comments or Chinese log messages to Python source.
|
|
12
|
+
|
|
13
|
+
## What this repository is
|
|
14
|
+
|
|
15
|
+
ReachReel is a fully local video narration pipeline:
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
source video -> scene detection -> VLM understanding -> narration script
|
|
19
|
+
-> local TTS -> subtitles -> audio mix -> FFmpeg render -> QA
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The product is a pipeline, not a timeline editor. The authoritative state is the work directory: `manifest.json` plus the stage artifacts.
|
|
23
|
+
|
|
24
|
+
## Repository layout
|
|
25
|
+
|
|
26
|
+
```text
|
|
27
|
+
src/reachreel/
|
|
28
|
+
cli/ # argparse entry points and command wiring
|
|
29
|
+
core/ # config, subprocess, JSON, logging, shared utilities
|
|
30
|
+
domain/ # pure models and timeline placement
|
|
31
|
+
engines/ # external model adapters (VLM, TTS, ASR)
|
|
32
|
+
generation/ # LLM script generation
|
|
33
|
+
i18n/ # UI language negotiation and catalog loader
|
|
34
|
+
locales/ # en.toml, zh-CN.toml UI copy
|
|
35
|
+
media/ # FFmpeg-facing work: scenes, subtitles, audio, render
|
|
36
|
+
pipeline/ # orchestration, caching, manifest, QA
|
|
37
|
+
prompts/ # language-specific prompts and content fallbacks
|
|
38
|
+
tests/
|
|
39
|
+
unit/ # fast, deterministic tests
|
|
40
|
+
integration/ # optional end-to-end tests (may require FFmpeg/models)
|
|
41
|
+
fixtures/ # small generated media fixtures
|
|
42
|
+
docs/
|
|
43
|
+
en/ # English versions of all docs
|
|
44
|
+
zh-CN/ # Chinese versions of all docs
|
|
45
|
+
*.md # bilingual index and glossary
|
|
46
|
+
inputs/ # local input root (ignored): bgm/, fonts/, models/
|
|
47
|
+
output/ # local workdir/render root (ignored)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Dependency direction is one-way:
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
cli -> pipeline -> {generation, engines, media, domain} -> core
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`domain/` must not import adapters, media tooling, or the pipeline. `engines/` and `media/` may import `domain/` and `core/`. Do not introduce cycles.
|
|
57
|
+
|
|
58
|
+
## Commands
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
# Environment (Python 3.11-3.12; 3.12 is recommended)
|
|
62
|
+
python3.12 -m venv .venv
|
|
63
|
+
uv pip install --python .venv/bin/python -e .
|
|
64
|
+
uv pip install --python .venv/bin/python -e '.[dev]' # apdev + lint/test tooling
|
|
65
|
+
|
|
66
|
+
# Quality gates
|
|
67
|
+
uvx ruff check src/reachreel tests scripts
|
|
68
|
+
.venv/bin/python -m unittest discover -s tests -v
|
|
69
|
+
|
|
70
|
+
# Repo conventions (same commands CI runs)
|
|
71
|
+
python3 scripts/check_commit_messages.py --range origin/main..HEAD
|
|
72
|
+
python3 scripts/check_changelog.py
|
|
73
|
+
python3 scripts/check_config_docs.py
|
|
74
|
+
apdev check-chars --charset-file scripts/apdev_charset.json $(find src/reachreel -name '*.py')
|
|
75
|
+
apdev check-imports
|
|
76
|
+
|
|
77
|
+
# Local hooks (once per clone)
|
|
78
|
+
pre-commit install
|
|
79
|
+
|
|
80
|
+
# Environment check
|
|
81
|
+
.venv/bin/reachreel doctor
|
|
82
|
+
|
|
83
|
+
# Build
|
|
84
|
+
uv build
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
The installed command is `reachreel`.
|
|
88
|
+
|
|
89
|
+
## Architecture invariants
|
|
90
|
+
|
|
91
|
+
- **Disk is the source of truth.** A job is defined by its work directory: `manifest.json` and the artifacts beside it. Do not keep a second in-memory source of truth.
|
|
92
|
+
- **One pipeline.** CLI commands, future HTTP endpoints, and the future local service must call the same `Pipeline` methods. Do not duplicate stage logic in a client.
|
|
93
|
+
- **Stages are independently runnable.** The canonical order is `probe -> vlm -> script -> tts -> subtitles -> mix -> render -> qa`. Every stage must validate its inputs and report the next actionable command when an input is missing.
|
|
94
|
+
- **Caching is explicit.** Cache keys must include every input that changes the result: source identity, model/provider, voice, prompt version, settings, and tool versions where relevant.
|
|
95
|
+
- **Local-first.** The default path must not require a cloud API. Remote providers are optional adapters, never a hidden requirement.
|
|
96
|
+
- **Local data is not repo data.** `inputs/` and `output/` are local-only; never commit input media or rendered output.
|
|
97
|
+
- **No timeline editor.** Do not add multi-track editing, transitions, or a full NLE. Keep the product focused on the handoff between existing tools and publishing.
|
|
98
|
+
|
|
99
|
+
## Code rules
|
|
100
|
+
|
|
101
|
+
- Python 3.11+, `from __future__ import annotations`.
|
|
102
|
+
- Prefer dataclasses and explicit types. Avoid global mutable state.
|
|
103
|
+
- Keep the CLI thin. Business logic belongs in `pipeline/`, `generation/`, `engines/`, or `media/`.
|
|
104
|
+
- Run external commands through `core.util.run`. Keep a bounded timeout and preserve the stderr tail in errors.
|
|
105
|
+
- All subprocess decoding must use UTF-8 with replacement. Never rely on the system locale.
|
|
106
|
+
- Write JSON and manifests with `core.util.atomic_write_json` (temporary file + fsync + replace).
|
|
107
|
+
- Validate user-provided input paths. Do not allow path traversal or symlink escape out of an allowed directory.
|
|
108
|
+
- Never write API keys, tokens, or credentials into `manifest.json`, logs, or generated packages.
|
|
109
|
+
- A new configuration key must be added in all of these places (`scripts/check_config_docs.py` verifies 1-3 in CI; 4 is checked in review):
|
|
110
|
+
1. `core/config.py`
|
|
111
|
+
2. `config.example.toml`
|
|
112
|
+
3. `docs/en/CONFIGURATION.md` and `docs/zh-CN/CONFIGURATION.md`
|
|
113
|
+
4. CLI options when users need to override it
|
|
114
|
+
- A new artifact or stage must be added to the orchestrator, `manifest.json`, the relevant docs, and tests.
|
|
115
|
+
|
|
116
|
+
## Internationalization
|
|
117
|
+
|
|
118
|
+
- Log messages and internal errors are canonical English.
|
|
119
|
+
- User-visible messages should be rendered through `reachreel.i18n.t()` once the i18n layer lands.
|
|
120
|
+
- Keep language-specific prompt text out of Python source. Prompt packs belong in `src/reachreel/prompts/<language>/`.
|
|
121
|
+
- Do not merge UI language and content language into one setting. Language settings are BCP 47 tags and engine-internal codes stay inside `engines/`: see `docs/en/LANGUAGES.md`.
|
|
122
|
+
- CI must reject CJK characters in Python source outside `prompts/` and `locales/` (`apdev check-chars` with `scripts/apdev_charset.json`; full-width punctuation is allowed because it is parsing data).
|
|
123
|
+
- Dependency direction must stay acyclic; `apdev check-imports` runs in CI.
|
|
124
|
+
|
|
125
|
+
## Documentation rules
|
|
126
|
+
|
|
127
|
+
- `README.md` is English; `README.zh-CN.md` is Simplified Chinese. Keep the command examples identical in both.
|
|
128
|
+
- Every document under `docs/` has a Chinese version in `docs/zh-CN/` and an English version in `docs/en/`. A change to one language must update the other in the same change.
|
|
129
|
+
- `docs/README.md` is the only bilingual navigation page.
|
|
130
|
+
- Every translated document starts with a language banner that links to the real counterpart.
|
|
131
|
+
- Never translate command names, option names, paths, or default values.
|
|
132
|
+
- Update `CHANGELOG.md` and `CHANGELOG.zh-CN.md` for behavior changes and breaking changes.
|
|
133
|
+
|
|
134
|
+
## Testing and verification
|
|
135
|
+
|
|
136
|
+
- Run `uvx ruff check src/reachreel tests` and `.venv/bin/python -m unittest discover -s tests -v` before handing off.
|
|
137
|
+
- Add characterization tests before restructuring behavior. A passing unit test is not proof that the CLI wiring works.
|
|
138
|
+
- Keep model-dependent tests out of the default suite. Use `say`, `--asr none`, and generated fixtures for smoke tests.
|
|
139
|
+
- For packaging changes, run `uv build` and verify the wheel contains `src/reachreel`, not the old package.
|
|
140
|
+
- Do not claim success without command output or test results.
|
|
141
|
+
|
|
142
|
+
## Change discipline
|
|
143
|
+
|
|
144
|
+
- Read the owning module and the relevant document before editing.
|
|
145
|
+
- Prefer the existing seam over a new abstraction. A new module needs one written sentence explaining why the current model cannot express the change.
|
|
146
|
+
- Do not rename files, modules, CLI flags, environment variables, or manifest fields silently. Add a migration note and update the docs in the same change.
|
|
147
|
+
- Do not rewrite pushed history. Do not commit secrets. Do not run destructive git commands without explicit confirmation.
|
|
148
|
+
- Release only what is worth announcing: at most one release per day, and only for a meaningful iteration. Docs, CI and tooling accumulate in `[Unreleased]`; retroactive tags must say "retroactive" in the tag message, the release title, and the first line of the notes.
|
|
149
|
+
- Use Conventional Commits in English, for example:
|
|
150
|
+
- `refactor(package): move reachreel to src layout`
|
|
151
|
+
- `feat(media): add scene-aware frame selection`
|
|
152
|
+
- `docs(i18n): add English user guide`
|
|
153
|
+
- `chore(ci): run ruff and unit tests`
|
|
154
|
+
- Changelog parity is enforced by `scripts/check_changelog.py` in CI: same version headings, same sections (English file in English, Chinese file in Chinese); a section that is empty in one language fails, and a bullet-count drift is only a warning unless `--strict` is passed.
|
|
155
|
+
- The format is enforced by `scripts/check_commit_messages.py`: locally through the `commit-message` pre-commit hook and in CI over the commits a push or pull request adds. Header is `type(scope): subject` (scope optional, `!` for a breaking change), at most 72 characters, no trailing period, English only.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
**English** | [简体中文](CHANGELOG.zh-CN.md)
|
|
2
|
+
|
|
3
|
+
# Changelog
|
|
4
|
+
|
|
5
|
+
## [Unreleased]
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- `[tool.apdev] pypi_repository = "reachreel"` selects the `[reachreel]` section of `~/.pypirc` for `apdev release`, so this project's uploads use its own PyPI account while the other repositories keep the default section. Requires `apdev >= 0.2.6`; DEVELOPMENT documents the resolution order, the first-upload ownership rule, and the `TWINE_REPOSITORY` fallback.
|
|
10
|
+
- PyPI-facing project metadata in `pyproject.toml`: `Project-URL` entries (homepage, repository, documentation, changelog, issues), eleven Trove classifiers, keywords, and the author. `twine check` passes for the wheel and the sdist, the licence renders through PEP 639 (`License-Expression: Apache-2.0` plus `License-File: LICENSE`/`NOTICE`), and the build emits Metadata-Version 2.5.
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- The `dev` extra did not actually list `pre-commit`, although `.pre-commit-config.yaml` and the docs tell contributors that `uv pip install -e '.[dev]'` provides it. It is part of the extra again (`pre-commit>=3.5`).
|
|
15
|
+
|
|
16
|
+
## [0.3.0] - 2026-11-22
|
|
17
|
+
|
|
18
|
+
### Added
|
|
19
|
+
|
|
20
|
+
- `src/reachreel/languages.py`: one registry of language profiles per `docs/en/LANGUAGES.md`, mapping BCP 47 tags to per-language defaults (speech rate, subtitle line length, font, engine code, dependency extra). Engine codes such as Kokoro's `a`/`b`/`z` now live only there.
|
|
21
|
+
- `tts_language` (BCP 47, `--tts-language`) and the voice/language guard: an unsupported tag or a voice whose language disagrees fails with the list of validated tags instead of producing a wrong-language voiceover that still passes QA. `reachreel doctor` prints the resolved `content` / `tts` / `asr` axes and the engine code.
|
|
22
|
+
- `doctor` reports the resolved TTS language and marks a planned language as missing.
|
|
23
|
+
- `docs/en/LANGUAGES.md` and its Chinese counterpart define the language and voice specification: BCP 47 tags only, four separate language axes, one language-profile registry, an engine capability contract, per-language dependency extras, and the validation gate a language must pass before it is called supported. Today only `zh-CN` TTS passes that gate.
|
|
24
|
+
- `render` warns when `output_height` is 0 and the source is larger than 1080p on its short side, because such a run silently keeps 4K, produces a much larger file, and makes the subtitle size look small. Found by running the Niagara 4K clip end to end.
|
|
25
|
+
- Representative-frame deduplication for the VLM stage: each extracted frame is thumbnailed to 16x16 grayscale and dropped when it barely differs from the last kept frame. New setting `vlm_frame_dedup` (default `4.0`, `0` disables) and `--vlm-dedup`; a static long shot now sends one frame instead of three, and the threshold is part of the VLM cache key.
|
|
26
|
+
- CI runs the "no CJK in Python source" guard as its own step, so a violation reports the file and line instead of hiding inside the full test output.
|
|
27
|
+
- Commit messages are now validated: `scripts/check_commit_messages.py` runs from the `commit-message` pre-commit hook and in CI over every commit a push or pull request adds.
|
|
28
|
+
- `.pre-commit-config.yaml` mirrors the CI convention checks locally (`apdev check-imports`, `apdev check-chars`, `ruff`, commit message), installed with `pre-commit install`; the older `.githooks` directory is gone, so clones that used it run `git config --unset core.hooksPath` once.
|
|
29
|
+
- `scripts/check_changelog.py` keeps `CHANGELOG.md` and `CHANGELOG.zh-CN.md` structurally in sync in CI: version headings, section order, and the language of each heading. A section that is empty in one language fails; a per-section bullet-count drift only warns unless `--strict` is passed, because one long English bullet can legitimately become two Chinese ones. It found the untranslated `### Added` / `### Known limitations` headings of the 0.1.0 entry, which are now Chinese.
|
|
30
|
+
- Development tooling moves to `apdev` (`apdev[dev]>=0.2.5`, APCore's shared toolkit) through a `dev` extra and `[tool.apdev]`. `apdev check-chars` with `scripts/apdev_charset.json` replaces the in-test CJK scan and allows full-width punctuation while keeping Chinese ideographs illegal, and `apdev check-imports` guards the dependency direction.
|
|
31
|
+
- `scripts/check_config_docs.py` keeps the configuration surface honest: every `Settings` field must exist in `config.example.toml` and be documented in both `CONFIGURATION.md` files, unknown keys fail, and a default drift only warns unless `--strict` is passed. Its first run found 18 `[qa]` thresholds missing from `config.example.toml`; they are now listed.
|
|
32
|
+
- `ci.yml` is split into a `checks` job on `ubuntu-latest` (commit messages, changelog parity, Python sources are English) and the macOS `test` job, so a bad commit subject fails in seconds instead of after a macOS runner is allocated. The unit-test matrix no longer repeats those checks twice.
|
|
33
|
+
- Unit tests for the mix filter graph: `mix_filter_graph()` now builds the ducking graph as a pure function, covered for narration-only, ambient-only, BGM-only, both side-chains, zero ambient volume, and duck-ratio clamping.
|
|
34
|
+
- `tests/integration/test_scenes.py`: FFmpeg-only fixtures with known cut points (2 s / 4 s) for `detect_scenes`, no-audio / mono / 5.1 clips for `probe_video` channel reporting, and 90° / 180° / 270° clips for coded-vs-display dimensions.
|
|
35
|
+
- `tests/integration/test_timeline.py`: covers the narration `atempo` fit path on real WAVs, and that a timeline that already fits is left untouched.
|
|
36
|
+
- `tests/integration/test_smoke.py::OnlyReuseTest`: `run --only tts`, `--only mix,render`, and `--only qa` are asserted not to redo earlier stages, using artifact hashes.
|
|
37
|
+
- Unit tests for timeline boundaries: empty list, no scenes, unknown scene id, overlong narration warning, and clips shorter than `tail_padding`.
|
|
38
|
+
- Retroactive `v0.1.0` (`b8a60ae`) and `v0.2.0` (`c9c3652`) tags, each with a GitHub release whose wheel and sdist were built from the tagged commit. Both are labelled retroactive because neither version had ever been tagged or announced.
|
|
39
|
+
|
|
40
|
+
### Changed
|
|
41
|
+
|
|
42
|
+
- `asr_language` now defaults to empty, which means "follow the primary subtag of `content_language`"; Chinese content still resolves to `zh`, so nothing changes for the supported pipeline.
|
|
43
|
+
- Hard subtitles now default to white text with a black outline and a soft shadow (`BorderStyle=1`, `subtitle_render = "outline"`), instead of the translucent black box that hid a large part of the frame. The stroke is about 6% of `subtitle_size` and can be overridden with `subtitle_outline` / `--subtitle-outline`.
|
|
44
|
+
- `subtitle_render = "box"` (or `--subtitle-render box`) restores the old look, with its padding now configurable via `subtitle_box_padding` / `--subtitle-box-padding`; `subtitle_render = "none"` draws plain white text without stroke or shadow. Work directories that recorded `render_settings` keep their previous mode.
|
|
45
|
+
- Supported platform narrowed to macOS 14+ on Apple silicon; Intel macOS is not targeted, and CI pins the current arm64 label.
|
|
46
|
+
- `reachreel doctor` now checks the host architecture and fails a `Platform` row on non-Apple-silicon machines instead of letting them run slowly.
|
|
47
|
+
- Minimum Python is now 3.11 (`mlx-audio` requires it) and the `tomli` fallback was removed; Python 3.10 can no longer install the package.
|
|
48
|
+
|
|
49
|
+
### Fixed
|
|
50
|
+
|
|
51
|
+
- CI now runs on `macos-15`: the `macos-14` label was retired and queued jobs failed with "The configuration 'macos-14-arm64-us-xl' is not supported".
|
|
52
|
+
- `render --crf` was parsed but never applied; the value is now forwarded to `Settings.crf` like `--height` / `--fps`, and a test asserts manifest `render_settings` are reused while CLI flags still win.
|
|
53
|
+
|
|
54
|
+
## [0.2.0] - 2026-11-22
|
|
55
|
+
|
|
56
|
+
### Added
|
|
57
|
+
|
|
58
|
+
- CI workflow (`.github/workflows/ci.yml`) running Ruff, the unit suite, and `uv build` on macOS for Python 3.10 and 3.12.
|
|
59
|
+
- Opt-in integration smoke test (`tests/integration/test_smoke.py`) covering `tts -> subtitle -> mix -> render -> qa` through the real CLI with macOS `say`.
|
|
60
|
+
- `tomli` fallback so Python 3.10 can load TOML catalogs and configuration.
|
|
61
|
+
- `manifest.json` now records `quality_flags` for degradations that do not stop the run (VLM scene failure, TTS segment failure, ASR fallback, QA warnings).
|
|
62
|
+
- Per-segment TTS retry and failure isolation; a single failed segment is skipped, while a total TTS failure aborts with a clear message.
|
|
63
|
+
- VLM and Whisper calls now retry with backoff.
|
|
64
|
+
- Optional `inputs/bgm/manifest.json` track catalog; `manifest.json` records `bgm_metadata`, and `reachreel licenses <workdir>` exports `licenses.md`.
|
|
65
|
+
- `VideoInfo` now records `coded_width` / `coded_height` alongside the rotated display size.
|
|
66
|
+
- Optional shared cache in the platform cache dir: VLM results keyed by a video fingerprint and TTS audio keyed by content, plus `reachreel cache info` and `cache clean`.
|
|
67
|
+
- Global `--cache-dir` / `--no-cache` flags.
|
|
68
|
+
- `subtitle_preset` platform safe areas (`douyin` / `reels` / `shorts` / `landscape`).
|
|
69
|
+
- `reachreel doctor --json` for machine-readable environment checks.
|
|
70
|
+
- The integration smoke now runs from a Chinese/space path, mixes a BGM track, and burns subtitles.
|
|
71
|
+
- `run --review-script` stops after the script stage and writes `script.md` for human review.
|
|
72
|
+
- Two-pass `loudnorm` (`two_pass_loudnorm`) with a single-pass fallback, and BGM fade-out (`bgm_fade_seconds` / `--bgm-fade`).
|
|
73
|
+
- Subtitle splitting keeps English words intact, and cue timing adds a pause bonus after sentence/clause punctuation.
|
|
74
|
+
|
|
75
|
+
### Changed
|
|
76
|
+
|
|
77
|
+
- Project license changed from MIT to Apache-2.0; added the full license text and a `NOTICE` file.
|
|
78
|
+
- `--height` is consistently documented and logged as display height for rotated footage.
|
|
79
|
+
- Subtitle line length and line count are enforced as hard limits; QA compares text with whitespace normalized.
|
|
80
|
+
- Mixing now measures loudness first and then linear-normalizes by default, which adds one audio-only pass.
|
|
81
|
+
- The shared cache now defaults to the platform cache dir (`~/Library/Caches/reachreel` on macOS) via `platformdirs`; the legacy `~/.cache/reachreel` is reused when the new directory does not exist yet.
|
|
82
|
+
|
|
83
|
+
### Fixed
|
|
84
|
+
|
|
85
|
+
- Test paths in `docs/en/DEVELOPMENT.md` and `docs/zh-CN/DEVELOPMENT.md` now match the `tests/unit/` layout.
|
|
86
|
+
- Reusing `scenes.json` no longer keeps stale video metadata; rotation and coded dimensions are refreshed from a fresh probe.
|
|
87
|
+
|
|
88
|
+
### Validation
|
|
89
|
+
|
|
90
|
+
- `output/ski` (1080x1920, 82s): full run with existing caches took 41s wall time; QA 20/20 pass.
|
|
91
|
+
- `output/niagara` (1920x1080, 93s): full run with existing caches took 56s wall time; QA 20/20 pass.
|
|
92
|
+
- `--review-script` wrote `script.md` on the ski work directory without re-running VLM or TTS.
|
|
93
|
+
|
|
94
|
+
## [0.1.0] - 2026-11-22
|
|
95
|
+
|
|
96
|
+
### Added
|
|
97
|
+
|
|
98
|
+
- Local video narration pipeline:
|
|
99
|
+
- FFmpeg scene detection and keyframe extraction;
|
|
100
|
+
- Ollama `qwen3-vl` scene understanding;
|
|
101
|
+
- Ollama `qwen3` narration writing with language-specific prompt packs;
|
|
102
|
+
- Kokoro-82M / MLX Chinese voiceover, with a macOS `say` fallback;
|
|
103
|
+
- `mlx-whisper` speech boundaries + script-based SRT/ASS subtitles;
|
|
104
|
+
- BGM / ambient / narration sidechain ducking;
|
|
105
|
+
- `ffmpeg-full` + libass hard subtitles;
|
|
106
|
+
- H.264/AAC output.
|
|
107
|
+
- CLI: `run`, `analyze`, `script`, `tts`, `subtitle`, `mix`, `render`, `qa`, `doctor`.
|
|
108
|
+
- Resumable scene, VLM, script, and TTS caches; `manifest.json` records settings, artifacts, and QA.
|
|
109
|
+
- QA gate: streams, duration, loudness/true peak, clipping, black/frozen frames, subtitle layout/overflow, and narration alignment.
|
|
110
|
+
- Bilingual CLI/UI via `--lang en|zh-CN` and `REACHREEL_LANG`.
|
|
111
|
+
- Independent content language via `--content-language zh|en` and `REACHREEL_CONTENT_LANGUAGE`.
|
|
112
|
+
- Language-specific prompt packs under `src/reachreel/prompts/{zh,en}`.
|
|
113
|
+
- Local input root `inputs/` (Git-ignored): `inputs/bgm/` for background music; `inputs/fonts/` and `inputs/models/` reserved for future use.
|
|
114
|
+
- Bilingual documentation: `README.md` / `README.zh-CN.md`, plus `docs/en/` and `docs/zh-CN/`.
|
|
115
|
+
- `src/` package layout: `cli`, `core`, `domain`, `engines`, `generation`, `i18n`, `locales`, `media`, `pipeline`, `prompts`.
|
|
116
|
+
|
|
117
|
+
### Known limitations
|
|
118
|
+
|
|
119
|
+
- Apple Silicon macOS only; TTS depends on MLX.
|
|
120
|
+
- VLM analyzes keyframes per scene, not the full video.
|
|
121
|
+
- Subtitles use segment/line-level timing, not word-level karaoke.
|
|
122
|
+
- BGM is selected randomly, not matched to mood.
|
|
123
|
+
- No GUI, batch queue, or publishing integration yet.
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
[English](CHANGELOG.md) | **简体中文**
|
|
2
|
+
|
|
3
|
+
# 变更记录
|
|
4
|
+
|
|
5
|
+
## [Unreleased]
|
|
6
|
+
|
|
7
|
+
### 新增
|
|
8
|
+
|
|
9
|
+
- `[tool.apdev] pypi_repository = "reachreel"` 让 `apdev release` 使用 `~/.pypirc` 的 `[reachreel]` 段:本项目走自己的 PyPI 账号,其他仓库继续用默认段。需要 `apdev >= 0.2.6`;DEVELOPMENT 里写清了优先级、首次上传决定归属,以及 `TWINE_REPOSITORY` 兜底方式。
|
|
10
|
+
- `pyproject.toml` 补齐 PyPI 页面所需元数据:`Project-URL`(主页、仓库、文档、变更记录、Issues)、11 条 Trove 分类、关键词与作者。`twine check` 对 wheel 与 sdist 均通过;许可证按 PEP 639 渲染(`License-Expression: Apache-2.0` 与 `License-File: LICENSE`/`NOTICE`),构建元数据版本为 2.5。
|
|
11
|
+
|
|
12
|
+
### 修复
|
|
13
|
+
|
|
14
|
+
- `dev` extra 里其实没有列 `pre-commit`,但 `.pre-commit-config.yaml` 和文档都告诉贡献者 `uv pip install -e '.[dev]'` 会带上它。现已重新加入(`pre-commit>=3.5`)。
|
|
15
|
+
|
|
16
|
+
## [0.3.0] - 2026-11-22
|
|
17
|
+
|
|
18
|
+
### 新增
|
|
19
|
+
|
|
20
|
+
- 新增 `src/reachreel/languages.py`:按 `docs/en/LANGUAGES.md` 建立的唯一语言档案登记表,把 BCP 47 标签映射到各语言的默认值(语速、字幕行字数、字体、引擎代码、依赖 extra)。Kokoro 的 `a`/`b`/`z` 等引擎代码只存在于这里。
|
|
21
|
+
- 新增 `tts_language`(BCP 47,`--tts-language`)与音色/语言护栏:不支持的语言标签、或音色语言与解析结果不一致时直接报错并列出已验证标签,而不是产出一段「能过 QA 但语言错了」的配音。`reachreel doctor` 会打印解析后的 `content` / `tts` / `asr` 三个维度与引擎代码。
|
|
22
|
+
- `doctor` 报告解析后的 TTS 语言,并把计划中的语言标为缺失。
|
|
23
|
+
- `docs/en/LANGUAGES.md` 与中文版定义了语言与音色规范:只使用 BCP 47 标签、四个独立的语言维度、唯一的语言档案登记表、引擎能力契约、按语言的依赖 extra,以及声明某语言「支持」前必须通过的验证门槛。目前只有 `zh-CN` 配音通过该门槛。
|
|
24
|
+
- `render` 在 `output_height = 0` 且素材短边大于 1080 时给出警告:这种跑法会静默保持 4K,文件明显变大,字幕在画面上也偏小。该问题由 Niagara 4K 素材的完整实跑发现。
|
|
25
|
+
- VLM 阶段的代表帧去重:每帧降采样成 16×16 灰度缩略图,与上一张保留帧区别过小就丢弃。新增配置 `vlm_frame_dedup`(默认 `4.0`,`0` 关闭)与 `--vlm-dedup`;静态长镜头现在只送 1 张而不是 3 张,阈值也计入 VLM 缓存 key。
|
|
26
|
+
- CI 把「Python 源码无 CJK」检查拆成独立步骤,违规时直接给出文件与行号,而不是埋在完整测试输出里。
|
|
27
|
+
- 新增提交信息校验:`scripts/check_commit_messages.py` 通过 `commit-message` pre-commit hook 与 CI 两条路径执行,检查 push 或 PR 新增的每个提交。
|
|
28
|
+
- 新增 `.pre-commit-config.yaml`,把 CI 的约定检查镜像到本地(`apdev check-imports`、`apdev check-chars`、`ruff`、提交信息),用 `pre-commit install` 安装;旧的 `.githooks` 目录已移除,用过它的 clone 需要执行一次 `git config --unset core.hooksPath`。
|
|
29
|
+
- 新增 `scripts/check_changelog.py`,在 CI 中校验 `CHANGELOG.md` 与 `CHANGELOG.zh-CN.md` 的结构一致性:版本标题、章节顺序、标题所用语言。某章节在一侧为空会失败;每章节条目数只作提示(一条长英文条目可以合法地拆成两条中文),`--strict` 才升级为错误。它当场发现了 0.1.0 里未翻译的 `### Added` / `### Known limitations`,现已改为中文。
|
|
30
|
+
- 开发工具改为 `apdev`(`apdev[dev]>=0.2.5`,APCore 系列共用工具包),通过 `dev` extra 与 `[tool.apdev]` 接入。`apdev check-chars` 配 `scripts/apdev_charset.json` 取代原来的 CJK 扫描:放行全角标点、汉字仍然非法;`apdev check-imports` 守护依赖方向无环。
|
|
31
|
+
- 新增 `scripts/check_config_docs.py`:每个 `Settings` 字段都必须出现在 `config.example.toml` 并在两份 `CONFIGURATION.md` 中有文档;未知键报错,默认值漂移只警告(`--strict` 才失败)。它第一次运行就发现 18 个 `[qa]` 阈值在 `config.example.toml` 里缺失,现已补齐。
|
|
32
|
+
- `ci.yml` 拆成 `checks`(`ubuntu-latest`:提交信息、变更记录一致性、Python 源码无 CJK)与 macOS `test` 两个 job:提交信息写错会在几秒内失败,而不是等 macOS runner 分配;单元测试矩阵也不再重复跑这些检查。
|
|
33
|
+
- 混音 filter graph 单元测试:`mix_filter_graph()` 抽成纯函数构造侧链图,覆盖仅旁白、仅环境音、仅 BGM、双路侧链、环境音音量为 0、压低比上下限。
|
|
34
|
+
- `tests/integration/test_scenes.py`:只依赖 FFmpeg 的 fixture,三色片段带 2s / 4s 已知切点用于 `detect_scenes`,另有无音轨 / 单声道 / 5.1 片段断言 `probe_video` 的声道数,以及 90° / 180° / 270° 片段断言编码尺寸与显示尺寸。
|
|
35
|
+
- `tests/integration/test_timeline.py`:覆盖真实 WAV 上的旁白 `atempo` 适配,以及本来就能放下的时间轴不被改动。
|
|
36
|
+
- `tests/integration/test_smoke.py::OnlyReuseTest`:用产物哈希断言 `run --only tts`、`--only mix,render`、`--only qa` 都不会重跑前面的阶段。
|
|
37
|
+
- 时间轴边界单元测试:空列表、无场景、未知场景 id、旁白超长告警、以及片段短于 `tail_padding` 的情况。
|
|
38
|
+
|
|
39
|
+
- 补打 `v0.1.0`(`b8a60ae`)与 `v0.2.0`(`c9c3652`)两个 tag,并各建一个 GitHub release,附上从对应提交构建的 wheel 与 sdist。两者都标注为 retroactive,因为当时既没打 tag 也没对外发布过。
|
|
40
|
+
|
|
41
|
+
### 变更
|
|
42
|
+
|
|
43
|
+
- `asr_language` 默认改为空,含义是「跟随 `content_language` 的主语言子标签」;中文内容仍解析为 `zh`,所以对已验证的链路没有行为变化。
|
|
44
|
+
- 硬字幕默认改为白字 + 黑描边 + 轻微阴影(`BorderStyle=1`,`subtitle_render = "outline"`),不再使用遮住大片画面的半透明黑底色块。描边宽度约为 `subtitle_size` 的 6%,可用 `subtitle_outline` / `--subtitle-outline` 覆盖。
|
|
45
|
+
- `subtitle_render = "box"`(或 `--subtitle-render box`)可恢复旧观感,其内边距现在可用 `subtitle_box_padding` / `--subtitle-box-padding` 调整;`subtitle_render = "none"` 输出纯白字、无描边无阴影。已在 `render_settings` 中记录过的旧工作目录沿用原模式。
|
|
46
|
+
- 支持平台收窄为 Apple Silicon 上的 macOS 14+;不支持 Intel macOS,CI 固定使用当前 arm64 标签。
|
|
47
|
+
- `reachreel doctor` 增加主机架构检查:非 Apple Silicon 机器上的 `平台` 一项会直接判失败,而不是默默跑出很慢的结果。
|
|
48
|
+
- 最低 Python 版本提高到 3.11(`mlx-audio` 的硬性要求),并移除 `tomli` 回退;Python 3.10 已无法安装本包。
|
|
49
|
+
|
|
50
|
+
### 修复
|
|
51
|
+
|
|
52
|
+
- CI 改用 `macos-15`:`macos-14` 标签已下线,排队任务会报错 “The configuration 'macos-14-arm64-us-xl' is not supported”。
|
|
53
|
+
- `render --crf` 之前只是被解析、从未生效;现在和 `--height` / `--fps` 一样写入 `Settings.crf`,并有测试断言 manifest 的 `render_settings` 会被复用、同时 CLI 参数优先。
|
|
54
|
+
|
|
55
|
+
## [0.2.0] - 2026-11-22
|
|
56
|
+
|
|
57
|
+
### 新增
|
|
58
|
+
|
|
59
|
+
- CI 工作流(`.github/workflows/ci.yml`):在 macOS 上对 Python 3.10 和 3.12 运行 Ruff、单元测试和 `uv build`。
|
|
60
|
+
- 可选的集成 smoke 测试(`tests/integration/test_smoke.py`):通过真实 CLI 用 macOS `say` 覆盖 `tts -> subtitle -> mix -> render -> qa`。
|
|
61
|
+
- 为 Python 3.10 增加 `tomli` 回退,用于读取 TOML 语言目录和配置。
|
|
62
|
+
- `manifest.json` 新增 `quality_flags`,记录不中断流程的降级(VLM 场景失败、TTS 段失败、ASR 回退、QA 警告)。
|
|
63
|
+
- TTS 单段重试与失败隔离;单段失败会跳过,全部失败才明确报错中断。
|
|
64
|
+
- VLM 和 Whisper 调用增加退避重试。
|
|
65
|
+
- 可选的 `inputs/bgm/manifest.json` 曲目目录;`manifest.json` 记录 `bgm_metadata`,`reachreel licenses <workdir>` 导出 `licenses.md`。
|
|
66
|
+
- `VideoInfo` 在显示宽高之外新增 `coded_width` / `coded_height`。
|
|
67
|
+
- 可选的平台缓存目录共享缓存:VLM 按视频指纹复用、TTS 按内容复用,并提供 `reachreel cache info` / `cache clean`。
|
|
68
|
+
- 全局 `--cache-dir` / `--no-cache` 参数。
|
|
69
|
+
- `subtitle_preset` 平台安全区(`douyin` / `reels` / `shorts` / `landscape`)。
|
|
70
|
+
- `reachreel doctor --json`,输出机器可读的环境检查结果。
|
|
71
|
+
- 集成 smoke 改为在中文/空格路径下运行,混入 BGM,并烧录字幕。
|
|
72
|
+
- `run --review-script` 在脚本阶段停下并输出 `script.md` 供人工确认。
|
|
73
|
+
- 两遍 `loudnorm`(`two_pass_loudnorm`,失败回退单遍)与 BGM 结尾淡出(`bgm_fade_seconds` / `--bgm-fade`)。
|
|
74
|
+
- 字幕切分不再拆断英文单词;时间分配在句末/逗号后加入停顿加成。
|
|
75
|
+
|
|
76
|
+
### 变更
|
|
77
|
+
|
|
78
|
+
- 项目许可证由 MIT 改为 Apache-2.0;补充完整许可证文本和 `NOTICE` 文件。
|
|
79
|
+
- 对带旋转的素材,`--height` 在文档和日志中统一为显示高度。
|
|
80
|
+
- 每行字数和行数成为硬约束;QA 文本比对会忽略空白差异。
|
|
81
|
+
- 混音默认先测量再线性归一,会多一次纯音频处理。
|
|
82
|
+
- 共享缓存默认改用平台缓存目录(macOS 为 `~/Library/Caches/reachreel`,通过 `platformdirs`);新目录不存在时继续复用旧 `~/.cache/reachreel`。
|
|
83
|
+
|
|
84
|
+
### 修复
|
|
85
|
+
|
|
86
|
+
- `docs/en/DEVELOPMENT.md` 和 `docs/zh-CN/DEVELOPMENT.md` 的测试路径已改为与 `tests/unit/` 目录一致。
|
|
87
|
+
- 复用 `scenes.json` 时不再保留过期的视频元数据;旋转和编码尺寸会用最新探测结果刷新。
|
|
88
|
+
|
|
89
|
+
### 验证
|
|
90
|
+
|
|
91
|
+
- `output/ski`(1080x1920,82s):复用已有缓存完整跑一遍,墙钟 41s;QA 20/20 通过。
|
|
92
|
+
- `output/niagara`(1920x1080,93s):复用已有缓存完整跑一遍,墙钟 56s;QA 20/20 通过。
|
|
93
|
+
- `--review-script` 在 ski 工作目录生成 `script.md`,未重跑 VLM 或 TTS。
|
|
94
|
+
|
|
95
|
+
## [0.1.0] - 2026-11-22
|
|
96
|
+
|
|
97
|
+
### 新增
|
|
98
|
+
|
|
99
|
+
- 本地视频解说流水线:
|
|
100
|
+
- FFmpeg 镜头检测、抽帧;
|
|
101
|
+
- Ollama `qwen3-vl` 画面理解;
|
|
102
|
+
- Ollama `qwen3` 写旁白,按语言加载 prompt pack;
|
|
103
|
+
- Kokoro-82M / MLX 中文配音,保留 macOS `say` 兜底;
|
|
104
|
+
- `mlx-whisper` 语音边界 + 原稿字幕,输出 SRT/ASS;
|
|
105
|
+
- BGM / 原声 / 旁白侧链闪避;
|
|
106
|
+
- `ffmpeg-full` + libass 硬字幕;
|
|
107
|
+
- H.264/AAC 成片。
|
|
108
|
+
- CLI:`run`、`analyze`、`script`、`tts`、`subtitle`、`mix`、`render`、`qa`、`doctor`。
|
|
109
|
+
- 场景、VLM、脚本、TTS 缓存可恢复;`manifest.json` 记录设置、产物与 QA。
|
|
110
|
+
- QA 闸门:流、时长、响度/真峰值、削波、黑帧/冻结帧、字幕布局/超框、旁白对齐。
|
|
111
|
+
- 双语 CLI/UI:`--lang en|zh-CN` 与 `REACHREEL_LANG`。
|
|
112
|
+
- 成片语言独立:`--content-language zh|en` 与 `REACHREEL_CONTENT_LANGUAGE`。
|
|
113
|
+
- 语言 prompt 包位于 `src/reachreel/prompts/{zh,en}`。
|
|
114
|
+
- 本地输入根目录 `inputs/`(被 Git 忽略):`inputs/bgm/` 放背景音乐;`inputs/fonts/` 与 `inputs/models/` 为未来预留。
|
|
115
|
+
- 双语文档:`README.md` / `README.zh-CN.md`,以及 `docs/en/` 与 `docs/zh-CN/`。
|
|
116
|
+
- `src/` 包结构:`cli`、`core`、`domain`、`engines`、`generation`、`i18n`、`locales`、`media`、`pipeline`、`prompts`。
|
|
117
|
+
|
|
118
|
+
### 已知限制
|
|
119
|
+
|
|
120
|
+
- 仅支持 Apple Silicon macOS;TTS 依赖 MLX。
|
|
121
|
+
- VLM 逐镜头看关键帧,不是完整视频理解。
|
|
122
|
+
- 字幕是段级/行级时间戳,不是逐字卡拉 OK。
|
|
123
|
+
- BGM 随机选择,不按情绪匹配。
|
|
124
|
+
- 尚无 GUI、批量队列与发布集成。
|