porter-workflow 0.2.0__tar.gz

porter_workflow-0.2.0/.gitignore

@@ -0,0 +1,110 @@
+# ---------------------------------------------------------------------------
+# porter-workflow
+# ---------------------------------------------------------------------------
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+wheels/
+sdist/
+MANIFEST
+
+# Virtualenvs / tooling caches
+.venv/
+venv/
+ENV/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.hypothesis/
+
+# ---------------------------------------------------------------------------
+# Secrets & local configuration  (NEVER commit)
+# ---------------------------------------------------------------------------
+config.json
+porter.json
+porter_config.json
+.env
+.env.*
+!.env.example
+*.cookies
+*.cookie
+cookies.txt
+
+# ---------------------------------------------------------------------------
+# Pipeline media output & scratch
+# ---------------------------------------------------------------------------
+porter_output/
+output/
+downloads/
+*.mp4
+*.mkv
+*.webm
+*.mov
+*.flv
+*.wav
+*.mp3
+*.flac
+*.aac
+*.m4a
+*.jpg
+*.jpeg
+*.png
+*.webp
+*.part
+*.ytdl
+*.ass
+*.srt
+*.vtt
+.tmp/
+tmp/
+*.tmp
+
+# ---------------------------------------------------------------------------
+# Local-only working area  (kept on disk, never published)
+# ---------------------------------------------------------------------------
+docs/
+
+# Skill assets are the one place media is source, not output: a subtitle sample
+# must be committable. Pipeline output dropped anywhere else is still ignored by
+# the rules above.
+!skills/**/*.png
+!skills/**/*.jpg
+!skills/**/*.jpeg
+!skills/**/*.webp
+!skills/**/*.gif
+!skills/**/*.svg
+!skills/**/*.srt
+!skills/**/*.ass
+
+# ---------------------------------------------------------------------------
+# Agent / editor / OS
+# ---------------------------------------------------------------------------
+.pi/**
+.memory/
+.cache/
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Pi session exports & local scratch
+pi-session-*.html
+*.session.html
+scratch/

porter_workflow-0.2.0/CHANGELOG.md

@@ -0,0 +1,239 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-24
+
+The first published release. v0.2 is a structural rewrite into one engine with
+three frontends (CLI, MCP server, Agent Skill). The `0.1.0` entry below was a
+commit, never a tag or an upload, so this is the first version anyone can install.
+
+### Added
+
+- **`PORTER_CACHE_DIR`** overrides where the job registry lives. Needed for more
+  than tidiness: `platformdirs` ignores `XDG_CACHE_HOME` on Windows (it asks the
+  Known Folder API), so there was no way to point two processes at a temporary
+  registry — which is exactly what the cross-process cancellation test has to do.
+  It is also the knob for a cache directory that is shared or read-only.
+- **TRANSLATE reuses its translation.** A re-run over unchanged cues skips the
+  backends and re-renders the subtitles from the cached text, so editing
+  `style.*` and re-running is free and still gives the new look. This was the one
+  phase with no reuse, on the grounds that its output includes the rendered
+  subtitle files and those depend on the style — which is true of the *files*,
+  and is why the **text** is cached and never the files. The cache is keyed on a
+  content hash of the sentences plus the target language and the engine's
+  identity (backend, model, endpoint), so changing the model or editing the cues
+  misses while changing the style hits. `--force` bypasses it.
+- **The MCP server shuts down gracefully on a signal.** `SIGINT`/`SIGTERM` (and
+  `SIGBREAK` on Windows) now ask every running job to stop and wait briefly for
+  them to unwind, instead of killing them mid-write. A job that unwinds records
+  `cancelled` itself, so the registry does not have to infer an interruption from
+  a dead PID later. An in-flight FFmpeg encode cannot be interrupted -- it has no
+  cancellation point inside it -- so a burn finishes its current step; the wait is
+  bounded for that reason, and a second signal skips it.
+- **Interrupting `porter run` reports what happened.** Ctrl+C records the job as
+  cancelled, prints one line, and exits `130`. Previously the `KeyboardInterrupt`
+  unwound to the top level and the user was shown the frame stack of whichever
+  library call was running -- ssl, socket, FFmpeg's pipe.
+- **Engine/frontend split.** Business logic now lives only in the `porter`
+  library. `porter_cli` and `porter_mcp` are thin consumers, and the boundary is
+  enforced by `import-linter`.
+- **`porter-mcp`**, an MCP server over stdio. Long jobs are exposed as
+  `start` / `status` / `result` / `cancel` rather than one blocking call.
+- **Persistent job registry**, written to the platform cache directory and
+  visible across processes, so a job can be inspected or cancelled from another
+  shell.
+- **New CLI subcommands**: `inspect`, `plan`, `jobs`, `doctor`, `config`.
+- **Local speech recognition** via `faster-whisper` behind the `asr-local`
+  extra: no API key, no network, no GPL code.
+- **Local media input** — a path or `file://` URL is accepted in addition to a
+  remote URL.
+- **`porter doctor`** probes FFmpeg, yt-dlp, the JavaScript runtime and every
+  ASR/translation backend, and reports which route a job will actually take.
+- **LLM translation backend**, alongside the key-free Bing, Google and MyMemory
+  backends.
+- **ASS subtitle styling** and bilingual / Chinese-only release renders.
+- **Launcher binaries** on GitHub Releases: a ~hundreds-of-KB bootstrap that
+  installs and updates the engine in `~/.porter/venv`, rather than a frozen
+  bundle that would pin a stale yt-dlp.
+
+### Changed
+
+- **Python 3.11 is now the floor**, up from 3.10. The declared `>=3.10` was not
+  true: the recommended `[asr-local]` extra could not install there at all,
+  because `faster-whisper` pulls in `onnxruntime`, which stopped publishing
+  `cp310` wheels after 1.23.2 — so `pip install porter-workflow[asr-local]`
+  failed outright on 3.10 while `requires-python` claimed it worked. Python 3.10
+  reaches end of life on 2026-10-31. The `tomli` dependency and its conditional
+  import are gone with it, since `tomllib` is standard from 3.11.
+- **Dependencies are locked.** `uv.lock` is committed and CI installs from it
+  with `uv sync --locked`, so the environment that is tested is the environment
+  that is described. Changing a dependency requires re-locking in the same
+  commit, which the gate enforces.
+- **Distribution renamed** from `porter-skill` to `porter-workflow`. The
+  installable Agent Skill keeps the name `porter-skill`.
+- **Library import path** changed from `porter_skill` to `porter`.
+- **Configuration** is resolved from `--config`, `$PORTER_CONFIG`, environment
+  variables, `./porter.json`, the platform user-config directory, then built-in
+  defaults. v0.1's probe for `SKILL.md` to decide where to write is gone; the
+  engine no longer knows how it is deployed.
+- **CLI is subcommand-based.** The v0.1 flags (`--config-show`, `--doctor`,
+  `--inspect`, `--skip-burn`, …) are replaced.
+- **YouTube downloads now require an external JavaScript runtime** (Deno
+  recommended, Node ≥ 20 accepted), because yt-dlp ≥ 2025.11.12 needs one to
+  solve YouTube's JS challenges.
+- **Optional backends are behind extras** (`llm`, `stt`, `asr-local`, `images`,
+  `mcp`, `all`), so the default install is pure Python plus FFmpeg.
+
+### Fixed
+
+- **The job registry is safe for concurrent writers in one process.** The lock
+  claimed to make that safe and did not: `msvcrt.locking` refuses rather than
+  waits when the same process already holds the byte range through another
+  handle, raising `OSError(EDEADLK, "Resource deadlock avoided")`. That is not an
+  exotic case — the MCP server publishes to the registry from one thread per job —
+  and measured, 16 concurrent publishers lost up to 5 records. A process-local
+  lock now serialises threads, with the file lock still serialising processes.
+- **A failed lock no longer reports the wrong error.** When taking the lock
+  failed, the cleanup tried to unlock a handle that had never locked it, which
+  raises `PermissionError` on Windows and *replaced* the `EDEADLK` that explained
+  the failure. The caller saw "permission denied" and never the cause.
+- **`--asr-engine` works.** It was written into `JobOptions.asr_engine` by all
+  three frontends and read by nobody, so `porter run --asr-engine whisper-api`,
+  MCP `porter_job_start(asr_engine=…)` and `porter_transcribe(engine=…)` were
+  silently ignored while the same value in `asr.engine` worked — which is
+  precisely what made it hard to notice. The flag now wins over the config key.
+  The test that appeared to cover this set the *config key* while its docstring
+  described the *flag*, which is how the gap survived.
+- **Platform subtitle tracks are written as UTF-8.** The `.json` (Bilibili) and
+  `.vtt` branches of the subtitle downloader read with `encoding="utf-8"` and
+  then wrote with `Path.write_text`'s default — the *locale* encoding, GBK on a
+  Windows console. Any cue holding an emoji or a replacement character raised
+  `UnicodeEncodeError` and killed a job whose subtitle had just been fetched
+  successfully. A mechanical test now rejects locale-encoded text writes across
+  `src/`, because a behavioural test cannot catch this on CI: Ubuntu's locale is
+  UTF-8, so the same code produces the same bytes there.
+- **The two release videos are announced as themselves.** BURN emitted both the
+  bilingual and the Chinese-only release as the generic `video` kind, so a
+  consumer matching on `ArtifactKind` — which its own docstring says downstream
+  agents do — could not tell them apart, even though `video_bilingual` and
+  `video_zh` existed for exactly that.
+- **`porter jobs cancel` no longer promises a checkpoint.** Its message said the
+  owning process "stops at the next checkpoint", referring to a resume mechanism
+  that was removed; it now says cancellation check.
+- **`porter jobs list` no longer crashes on Windows.** `os.kill(pid, 0)` reports a
+  dead PID as `OSError(ERROR_INVALID_PARAMETER)` there rather than
+  `ProcessLookupError`, and it escaped unhandled -- so a single stale record, which
+  is exactly what a killed job leaves behind, aborted the whole registry read.
+  The command that tells you about interrupted jobs was the one they broke.
+- **The recycled-PID guard now works on Windows.** `process_marker` reads the
+  process creation time via `GetProcessTimes` instead of falling back to a bare
+  PID, and checks the exit code first: `OpenProcess` keeps succeeding for a
+  terminated process for a moment after it dies, so the creation time alone would
+  have reported a dead owner as identifiable. Liveness is answered per platform
+  rather than through `os.kill(pid, 0)`, which has the same blind spot.
+- **`ffmpeg.auto_tune` and `asr.audio_denoise` are honoured.** Both were parsed,
+  documented, and read by nothing. `auto_tune=false` now skips the hardware-tier
+  trial encode and uses `ffmpeg.preset`/`ffmpeg.crf` as configured, in BURN,
+  `porter_burn` and `porter doctor` alike; `audio_denoise` is the default for
+  `JobOptions.audio_denoise`, which the CLI and MCP override only when asked to.
+- **`porter plan` no longer drops `--config`.** `plan_for` re-resolved the
+  configuration whenever it was given neither a context nor options, so the plan
+  described a different run from the one the same command line would perform --
+  every setting that comes from configuration (`asr.engine`, `translator`, ffmpeg,
+  subtitle style) was read from defaults. The CLI and the MCP tool now pass a
+  context built from the configuration they already resolved.
+- **Naming an unavailable ASR backend is no longer silent.** Naming a backend
+  promotes it and keeps the rest as fallbacks, so a missing one is not fatal --
+  which is exactly why it needs saying: asking for VideoCaptioner's `bijian` and
+  quietly getting Bcut's output is indistinguishable from success. It is now
+  reported at assembly time, before the expensive work.
+- **`porter_doctor` no longer tells agents to call a tool that does not exist.**
+  Its description referred to `porter_run`.
+- **Truncated encodes are no longer published as finished videos.** Release
+  output is written to a temporary path and renamed only after `ffprobe`
+  confirms it is readable. In v0.1 the rename was unconditional, so a failed
+  encode could be mistaken for a complete render.
+- **`import porter` no longer fails on Python 3.10.** `tomli` is declared for
+  the 3.10 floor instead of relying on the 3.11 standard-library `tomllib`.
+- **Non-ASCII paths and titles no longer crash subprocess reads.** Child output
+  is decoded with `errors="replace"` rather than the locale codec, which is
+  ASCII under the `POSIX`/`C` locale.
+- **CLI, MCP and skill agree on one engine**, so a fix lands in all three at
+  once; v0.1 duplicated the pipeline across entry points.
+- **yt-dlp failures are reported as data, not as a traceback.** A removed video,
+  a geo-block, a bot check or a format selector that matches nothing all arrive
+  as `yt_dlp.utils.YoutubeDLError`; only the metadata path let one escape, so the
+  user got a Python stack trace for a condition the tool is meant to explain. It
+  is now mapped to `ExtractionError` with the URL, platform and original message.
+- **Subtitles no longer cut an English word in half.** The midpoint pass in
+  `split_chinese_text_by_phrase` used a raw character index, serving a real
+  subtitle as `这里的所有内容都在 Wi` / `ndows 上本地运行` — despite the function
+  promising not to cut words apart. The cut now snaps to the nearest word
+  boundary, and a piece that is one unbreakable token is left whole.
+- **`porter plan` accepts `--cookies` / `--cookies-from-browser`.** It inspects
+  the source, so it needs the credentials a run needs; its own blocker text told
+  users to pass flags the command did not have. (`inspect` always had them.)
+- **Glyphs degrade to ASCII on a non-UTF-8 console.** A GBK or cp1252 terminal
+  cannot encode `✓`/`✗`, and `errors="backslashreplace"` printed a literal
+  `\u2713` at the user. Symbols the console *can* encode (`→`, `…`, `·`) are
+  still used; only the impossible ones fall back.
+
+### Removed
+
+- **`porter_mcp/progress.py`, and the claim that went with it.** A complete
+  bridge from engine events to MCP progress notifications — phase weights,
+  monotonic percent, the lot — imported by nothing, while `server.py` listed
+  "progress notifications" among the things the frontend owns. It does not send
+  any: jobs run on background threads and are polled, and the blocking stage
+  tools are short enough that a token would buy nothing. The docstring now says
+  so instead of the module implying otherwise.
+- **Dead helpers whose docstrings described capabilities they did not have.**
+  `JobStore._observe_cancel_now` ("exists for the watchdog's own tests"; no test
+  called it), `translate.base.apply_texts_to_items` (promised a `strict=True`
+  length check that never ran, because the chain applies text through
+  `_cues_from_sentences`), `doctor.guides.platform_hint`, and
+  `SubtitleSet.has_translation` — whose real check is
+  `has_chinese_translation`, since a backend echoing its input satisfies the
+  former.
+- **Unused checkpoint scaffolding on `RunContext`** (`checkpoint_dir`,
+  `stage_dir`, `stage_cached`). Nothing called it, no code ever set
+  `checkpoint_dir`, and its docstrings advertised a resume-from-disk feature
+  that did not exist. Stage-output reuse is real, but it lives in the PREPARE,
+  TRANSCRIBE and BURN implementations instead, gated on `--force`.
+- **The claimed key-free speech-to-text path.** Every key-free ASR endpoint
+  (Bcut, Google Web) was measured and found non-functional as of 2026-09-22.
+  Transcription now needs an API key or the VideoCaptioner CLI, and
+  `porter doctor` says so before a job starts.
+- **Hard dependencies on `openai`, `pillow`, `SpeechRecognition`** in the
+  default install.
+
+### Security
+
+- Added [`SECURITY.md`](SECURITY.md) and a private vulnerability reporting
+  process.
+- The engine never writes to stdout (enforced by ruff rule `T20`); stdout is the
+  MCP JSON-RPC channel, so this is a protocol-integrity guarantee, not style.
+
+## [0.1.0] - 2026-08-30
+
+Initial release, published as `porter-skill` (Python distribution and Agent
+Skill of the same name).
+
+### Added
+
+- Automated video localization pipeline for YouTube, X/Twitter, Instagram,
+  TikTok and Bilibili: download, transcribe, translate, burn.
+- Multi-engine ASR chain and multi-backend subtitle translation chain.
+- Bilingual and Chinese-only hard-subbed release videos, plus ASS/SRT subtitle
+  assets and a standardised `raw/` + `cooked/` output layout.
+- Agent Skill packaging (`SKILL.md`, scripts, references, example config).
+
+[Unreleased]: https://github.com/RolinShmily/porter-workflow/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/RolinShmily/porter-workflow/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/RolinShmily/porter-workflow/commit/c2e4286

porter_workflow-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RoL1n_SrP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

porter_workflow-0.2.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.5
+Name: porter-workflow
+Version: 0.2.0
+Summary: Automated video localization, multi-engine ASR, subtitle translation, and dual-version FFmpeg hardsub pipeline for AI agents, CLI, and MCP hosts.
+Project-URL: Homepage, https://github.com/RolinShmily/porter-workflow
+Project-URL: Repository, https://github.com/RolinShmily/porter-workflow
+Project-URL: Issues, https://github.com/RolinShmily/porter-workflow/issues
+Project-URL: Documentation, https://github.com/RolinShmily/porter-workflow/tree/main/docs
+Project-URL: Changelog, https://github.com/RolinShmily/porter-workflow/blob/main/CHANGELOG.md
+Author: RoL1n_SrP
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Keywords: agent-skill,asr,ffmpeg,hardsub,mcp,subtitles,translation,video-localization,youtube
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.11
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: requests>=2.31
+Requires-Dist: yt-dlp[default]>=2025.11.12
+Provides-Extra: all
+Requires-Dist: faster-whisper>=1.0; extra == 'all'
+Requires-Dist: fastmcp>=2.11; extra == 'all'
+Requires-Dist: json-repair>=0.30; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: pillow>=10.0; extra == 'all'
+Requires-Dist: speechrecognition>=3.10; extra == 'all'
+Provides-Extra: asr-local
+Requires-Dist: faster-whisper>=1.0; extra == 'asr-local'
+Provides-Extra: dev
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: images
+Requires-Dist: pillow>=10.0; extra == 'images'
+Provides-Extra: llm
+Requires-Dist: json-repair>=0.30; extra == 'llm'
+Requires-Dist: openai>=1.0; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.11; extra == 'mcp'
+Provides-Extra: stt
+Requires-Dist: speechrecognition>=3.10; extra == 'stt'
+Description-Content-Type: text/markdown
+
+# Porter Workflow
+
+<p align="center">
+  <b>English</b> | <a href="README_zh.md">简体中文</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/RolinShmily/porter-workflow/actions/workflows/test.yml"><img alt="CI" src="https://github.com/RolinShmily/porter-workflow/actions/workflows/test.yml/badge.svg"></a>
+  <a href="https://pypi.org/project/porter-workflow/"><img alt="PyPI" src="https://img.shields.io/pypi/v/porter-workflow"></a>
+  <img alt="Python 3.11 - 3.13" src="https://img.shields.io/badge/python-3.11%20%E2%80%93%203.13-blue">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
+</p>
+
+**Porter Workflow** is an automated video localization pipeline: give it a video
+URL, get back a standardised asset bundle plus hard-subbed release videos with
+bilingual and Chinese-only subtitles.
+
+It ships as **one engine with three frontends**:
+
+| Frontend | Entry point | For |
+| --- | --- | --- |
+| `porter` (CLI) | `porter "<URL>"` | Humans and shell scripts |
+| `porter-mcp` | `uvx --from "porter-workflow[mcp]" porter-mcp` | AI agents via Model Context Protocol |
+| `porter-skill` | `npx skills add RolinShmily/porter-workflow` | Agents that use the Agent Skills spec |
+
+All three call the same `porter` library. The engine contains no argument
+parsing and never writes to stdout — a requirement, because in an MCP stdio
+server stdout *is* the JSON-RPC channel.
+
+> **Status: `v0.2.0` is the current development line on `main`.**
+> The v0.2 rewrite — one engine, three frontends — has landed. The v0.1
+> implementation is preserved in git history at commit `b5fd577`.
+
+---
+
+## Installation
+
+Requires **Python ≥ 3.11**.
+
+```bash
+# CLI, minimal install (pure-Python; translation works without a key, but
+# transcription does NOT -- see "Transcription needs a key" below)
+uvx porter-workflow "<URL>"
+
+# CLI with every optional backend
+uvx --from "porter-workflow[all]" porter "<URL>"
+
+# Persistent install
+pipx install "porter-workflow[all]"
+```
+
+### System dependencies
+
+These are **not** Python packages and must be on `PATH`:
+
+| Dependency | Needed for | Notes |
+| --- | --- | --- |
+| **FFmpeg + ffprobe** | Everything | Must be built **with `libass`** for hardsubbing. Verify: `ffmpeg -filters \| grep subtitles` |
+| **Deno** (recommended) | YouTube downloads | yt-dlp ≥ 2025.11.12 needs an external JS runtime to solve YouTube's JS challenges. Node ≥ 20 also works. |
+
+Check everything at once:
+
+```bash
+porter doctor
+```
+
+### Transcription needs a key (or the VideoCaptioner CLI)
+
+**There is no working key-free speech-to-text path.** This is measured, not
+theoretical — as of 2026-09-22, on a real 10-minute video:
+
+| ASR backend | Status |
+| --- | --- |
+| Whisper API | Needs `OPENAI_API_KEY` (or a compatible endpoint) |
+| VideoCaptioner CLI | Needs the `videocaptioner` package installed separately |
+| Bcut | Host answers, but returns **zero utterances** |
+| Google Web (`[stt]`) | Returns the empty result `{"result":[]}` for **every** request |
+
+Both key-free endpoints are reverse-engineered and neither transcribes any
+more. Google Web's response is also malformed at the HTTP level, so the read
+fails outright rather than merely returning nothing. Bcut's failure is the more
+ambiguous of the two -- the host answers, so it could be a quota or a changed
+field rather than a dead endpoint -- which is why it keeps an "unverified" label
+in the source.
+
+So a bare `uvx porter-workflow "<URL>"` will download and standardise the video
+and then fail at the transcription phase with
+`every speech-to-text backend failed`. To get subtitles, do one of:
+
+```bash
+# Option A: an LLM key (also improves translation quality a lot)
+export OPENAI_API_KEY=sk-...
+porter "<URL>" --burn skip
+
+# Option B: install VideoCaptioner and use its engines
+pip install videocaptioner
+porter "<URL>" --asr-engine bijian --burn skip
+```
+
+**Translation is unaffected.** Bing, Google and MyMemory all still work without
+a key; each was probed against its live endpoint and returned real Chinese. Only
+transcription needs credentials.
+
+`porter doctor` reports which route a job will actually take before you start it.
+
+### Optional extras
+
+| Extra | Adds | Enables |
+| --- | --- | --- |
+| `[llm]` | `openai`, `json-repair` | LLM translation + Whisper API ASR |
+| `[stt]` | `SpeechRecognition` | Google Web STT — **measured non-functional**, see below |
+| `[images]` | `pillow` | Cover image handling |
+| `[mcp]` | `fastmcp` | The `porter-mcp` server |
+| `[all]` | all of the above | — |
+
+`videocaptioner` is **deliberately not a dependency.** It is GPL-3.0 (this
+project is MIT) and pins `python<3.13`. Porter detects it at runtime and, if
+present, uses it as an extra ASR/translation backend across a process boundary.
+Install it yourself if you want those engines:
+
+```bash
+pip install videocaptioner
+```
+
+---
+
+## Usage
+
+```bash
+# Inspect a link without downloading anything
+porter inspect "<URL>"
+
+# Full pipeline: download → transcribe → translate → burn
+porter "<URL>" -o ./porter_output
+
+# Subtitles only, no video encoding
+porter "<URL>" --burn skip
+
+# Diagnose the environment
+porter doctor
+
+# Show resolved configuration (secrets masked)
+porter config list
+```
+
+### Output layout
+
+```
+<output_dir>/<video_id>_<safe_title>/
+├── raw/
+│   ├── video.mp4                 H.264 + AAC + faststart master
+│   ├── audio.wav                 16 kHz mono reference track
+│   ├── audio_enhanced.wav        denoised track used only for ASR
+│   ├── transcript.json/.txt      reconstructed sentence script book
+│   ├── subtitle.srt              platform-provided source subtitles, if any
+│   ├── cover.jpg
+│   └── metadata.json
+└── cooked/
+    ├── subtitle_bilingual.{srt,ass}
+    ├── subtitle_zh.{srt,ass}
+    ├── video_bilingual.mp4
+    └── video_zh.mp4
+```
+
+### Configuration
+
+Resolved in this order, highest priority first:
+
+1. `--config <path>`
+2. `$PORTER_CONFIG`
+3. Environment variables (`OPENAI_API_KEY`, `PORTER_ASR_ENGINE`, …)
+4. Project-level `./porter.json`
+5. User-level config directory (`platformdirs`)
+6. Built-in defaults
+
+---
+
+## MCP server
+
+```json
+{
+  "mcpServers": {
+    "porter": {
+      "command": "uvx",
+      "args": ["--from", "porter-workflow[mcp]", "porter-mcp"]
+    }
+  }
+}
+```
+
+Long jobs are exposed as a start/status/result/cancel API rather than one
+blocking call, because encoding a 1080p video can take tens of minutes.
+
+---
+
+## Development
+
+```bash
+uv sync --extra all --extra dev      # installs exactly what uv.lock pins
+
+ruff check src          # includes T20: the engine must not print()
+mypy src
+lint-imports            # enforces the engine/frontend boundary
+pytest
+```
+
+[`CONTRIBUTING.md`](CONTRIBUTING.md) documents the full gate, the architecture
+rules those tools enforce, and the licence rules for new dependencies.
+
+Repository layout:
+
+```
+src/porter/        engine (library) — all business logic lives here
+src/porter_cli/    CLI frontend
+src/porter_mcp/    MCP frontend
+skills/porter-skill/   Agent Skill assets (SKILL.md, scripts, references)
+tests/{unit,regression,integration}/
+```
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+## Acknowledgements
+
+Porter is built on other people's work, and the debt is worth stating plainly:
+
+* **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** — downloading from five
+  platforms is a solved problem rather than five scrapers, because of this.
+* **[VideoCaptioner](https://github.com/WEIFENG2333/VideoCaptioner)** (GPL-3.0) —
+  its sentence segmentation, alignment and subtitle-processing design shaped the
+  approach in `porter.subtitles` and the ASR chain. Ideas only: no code was
+  copied, and it is never imported — only run as an external process, which is
+  why porter can stay MIT.
+* **[FFmpeg](https://ffmpeg.org/) and
+  [libass](https://github.com/libass/libass)** — the entire media layer:
+  standardisation, denoising and professional ASS rendering.
+
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) records every component,
+its licence, and whether porter depends on it, optionally installs it, or only
+spawns it as a subprocess.
+
+---
+
+## Contributing
+
+Contributions are welcome. [`CONTRIBUTING.md`](CONTRIBUTING.md) covers the
+development setup and the gate every change must pass; [`SECURITY.md`](SECURITY.md)
+explains how to report a vulnerability privately; release history lives in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).