Porter Workflow

English | 简体中文

Porter Workflow takes a video URL or a local file and produces a localized release: a standardized asset bundle, bilingual and Chinese-only subtitles, and hard-subbed MP4s.

How it works

URL / local file
      │
      ▼
PREPARE     download, standardize, fetch platform subtitles, extract audio
      │
      ▼
TRANSCRIBE  use the platform's subtitle track, or run speech recognition
      │
      ▼
TRANSLATE   produce target-language subtitles (default: zh-Hans)
      │
      ▼
BURN        render bilingual / Chinese-only hard-subbed MP4s

Completed phases are reused on a rerun. --force redoes them, --only-phase stops after one, and --burn skip stops before encoding.

Supported platforms

Downloads go through yt-dlp, so other sites it supports may work, but only these platforms have explicit specs. A native track is requested, not guaranteed: rate limiting can make the fetch fail, and the ASR chain then takes over.

Backends by phase

PREPARE

• URL — yt-dlp download; local file — used in place.
• FFmpeg normalizes video to H.264/AAC and audio to 16 kHz mono.
• Deno (or Node ≥ 20) is recommended for YouTube's JS challenges.

TRANSCRIBE

The first available backend wins. --asr-engine NAME moves a named backend to the front but keeps the rest as fallbacks. A Chinese platform track skips the translation phase entirely.

TRANSLATE

The first backend that produces usable text wins. For a Chinese target, a response without CJK characters is rejected and the next backend is tried. --translator NAME promotes a backend to the front, like --asr-engine. --target-lang defaults to zh-Hans.

BURN

Burning requires FFmpeg with libass. Fonts, sizes, colors, margins and fades are configurable under the style section.

Install

Requires Python ≥ 3.11.

System dependencies (not Python packages, must be on PATH):

# Recommended: local, key-free, offline transcription
uvx --from "porter-workflow[asr-local]" porter "<URL>"

# Every optional backend, including WebUI support
uvx --from "porter-workflow[all]" porter "<URL>"

# WebUI workbench
uvx --from "porter-workflow[web]" porter-web

# Persistent install
pipx install "porter-workflow[all]"

# Check the environment
porter doctor

A minimal install without [asr-local] or [llm] can download and translate, but cannot transcribe unless a platform subtitle track exists or the external VideoCaptioner CLI is installed. porter doctor reports the route a job will actually take.

Usage

porter inspect "<URL>"              # Inspect a link without downloading
porter plan "<URL>"                 # Show the exact route and expected failures
porter "<URL>"                      # Full pipeline
porter "<URL>" -o ./porter_output   # Choose the output directory
porter "<URL>" --burn skip          # Subtitles only
porter doctor                       # Diagnose the environment
porter config list                  # Show resolved config (secrets masked)

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

Frontends

All four call the same engine. MCP setup details are in skills/porter-skill/references/MCP.md; restricted Windows hosts are covered in skills/porter-skill/references/HOSTS.md.

Configuration

Resolved in this order, highest priority first:

1. --config <path>
2. $PORTER_CONFIG
3. Environment variables (they override the selected file)
4. Nearest project config: porter.json → porter.toml → config.json
5. User config under platformdirs (only if there is no project config)
6. Built-in defaults

porter config list                     # Effective values + source, secrets masked
porter config get llm                  # Show one section
porter config set llm.model=deepseek-chat
porter config set llm.api_key=sk-...   # Writes user-level config by default

The complete key table, defaults and examples are in skills/porter-skill/references/CONFIG.md.

Build and develop

Development needs Python 3.11–3.13, uv, FFmpeg + libass, and Deno or Node ≥ 20. The runtime dependencies are yt-dlp[default], requests, pydantic and platformdirs; everything else is an optional extra.

uv sync --extra all --extra dev      # Install exactly what uv.lock pins

ruff check src tests scripts        # Lint; T20 enforces no print() in the engine
mypy src scripts                    # Strict type checking
lint-imports                        # Engine/frontend dependency contracts
pytest -m "not network"             # Offline suite

Repository layout:

src/porter/
├── __init__.py       stable public API (lazy exports), __version__
├── core/             engine — all business logic
├── cli/              CLI frontend
├── mcp/              MCP frontend
└── webui/            Gradio WebUI frontend (HITL workbench)
skills/porter-skill/  Agent Skill assets (SKILL.md, scripts, references)
scripts/              developer / release helper scripts (launcher.py)
docs/                 development, architecture, reference, design, images
tests/{unit,regression,integration}/

• Documentation index
• Architecture overview
• Development gate
• CLI reference
• Contributing

License

MIT. See LICENSE. Third-party components and their licences are listed in THIRD_PARTY_NOTICES.md.