Podcast MCP
# Podcast MCP
FOSS podcast production toolkit: multitrack projects, per-track transcription, transcript-driven tightening, FFmpeg processing, ShareCut Studio (a full DAW-style editor in the browser and the desktop app), and agent skills under `.agents/`. The scope of the current beta is in [docs/beta-plan.md](docs/beta-plan.md).
**Requirements:** Python 3.11+, [uv](https://github.com/astral-sh/uv) recommended (`install.sh` falls back to `.venv` + `pip`), and a matching FFmpeg/FFprobe 9.0.2 or later 9.x pair for source use. Desktop packaging selects a pinned prebuilt 9.0.2 pair. The release catalog pins the same platform archives for CI and desktop packaging.
## Quick start
```bash
git clone <repo-url> && cd sharecut-studio
./install.sh
source .venv/bin/activate # or: uv run podcast β¦
podcast doctor
# Whisper defaults to large-v3-turbo (~1.6 GB, first transcribe). Smaller: ./install.sh --whisper-model small.en
```
`./install.sh` installs a **contributor** set (`dev` + `gui` + `relay`). Optional downloads and extras: [docs/setup.md](docs/setup.md#optional-downloads-and-extras).
Choose a downloaded Whisper model for one standalone transcription with `podcast transcribe --project β¦ --model small.en`; use `podcast setup --whisper-model small.en` or `PODCAST_WHISPER_MODEL` to make that choice the machine default.
`podcast transcribe` reports the number of tracks processed by that run. When there are no dialogue tracks to process, it reports `Transcribed 0 track(s).` and warns on stderr.
No supported system pair? Use the [prebuilt importer](docs/setup.md#acquire-the-pinned-ffmpeg-pair). Offline validation uses an explicit pinned archive through the same importer. Pair selection and the tested release policy, including process-local reuse of successful unchanged admission, are documented in [docs/setup.md](docs/setup.md#ffmpeg-version-and-pair-policy).
Explicit health checks still run fresh bounded version probes.
Agent config is tool-agnostic under [.agents/](.agents/) (skills, rules, MCP template). Register MCP per [docs/setup.md](docs/setup.md). With `podcast gui` running on loopback, **Connect agentβ¦** (home or Menu) copies `http://127.0.0.1:8765/mcp` for URL-only clients. Use the `podcast-setup` skill when onboarding.
Codex UI edits have project-local [Impeccable design hooks](docs/setup.md#impeccable-design-hooks). Review and trust them in Codex Settings β Hooks after cloning or updating their definitions.
## Maximal install (all extras)
Every pip extra, plus the models `podcast bootstrap` fetches: about 360 MB for the word aligner and about 80 MB for the speaker model. No extra pulls torch. Prefer the Quick start above for everyday CLI/MCP/GUI work.
```bash
git clone <repo-url> && cd sharecut-studio
uv sync --all-extras
source .venv/bin/activate # or: uv run β¦
podcast bootstrap
podcast doctor
# Optional ShareCut Studio UI (needs Node 24+):
cd gui/web && npm ci && npm run build && cd ../..
```
Notes (verified in a disposable Linux Docker image):
- `uv sync --all-extras` installs every pip extra (`dev`, `gui`, `relay`, `object-store`, `prosody`).
- A bare `podcast bootstrap` installs Whisper, RNNoise, the word aligner and the speaker model, and so does Studio's Get ready card. `podcast bootstrap --component word-aligner` installs just the aligner; once downloaded, precise word boundaries (`transcribe.forced_alignment.enabled`, English) turn on by default; until then they stay unavailable and the pipeline reports word times as Whisper-only (Studio: download it next to the Pipeline tab's Precise word boundaries field).
- Without `uv`: `python3 -m venv .venv && .venv/bin/pip install -e ".[all]"` then the same bootstrap/doctor steps.
Detail: [docs/setup.md Β§ Maximal install](docs/setup.md#maximal-install-all-extras). Operators can use the [read-only public mirror check](docs/setup.md#check-a-public-bootstrap-mirror) to verify bootstrap object availability without downloading payloads.
The frontend CI suite uses a [locked exporter dependency group](docs/setup.md#frontend-exporter-dependencies) for its four generated-file checks. Browser suites keep the full GUI environment.
## Repo layout
| Path | Purpose |
|------|---------|
| `src/podcast_mcp/` | Python package β CLI, MCP, services, domain, GUI API, Extensions SPI |
| `podcast_online` | Optional private/provider extension, installed independently when needed; its source is not part of this repository |
| `src/podcast_relay/` | FOSS reverse-tunnel edge (`podcast-relay`) |
| `gui/web/` | ShareCut Studio viewer (React + Vite) |
| `deploy/relay/` | FOSS host-online share relay (Docker Compose examples) |
| `contracts/` | Published caps / feature-id contract artifacts |
| `.agents/` | Skills, rules, MCP template, pipeline defaults |
| `docs/` | Architecture and feature docs |
| `tests/` | Pytest suite and fixtures (`aligned_dialogue`, β¦) |
| `schemas/` | `episode.sharecut` JSON Schema |
## Episode workspace
```bash
podcast episode init --dir /path/to/my_episode
podcast track add --project /path/to/my_episode/episode.sharecut --id host --file raw/host.wav --role dialogue
podcast pipeline run --project /path/to/my_episode/episode.sharecut
```
**ShareCut Studio (editor):**
```bash
uv sync --extra gui
cd gui/web && npm install && npm run build && cd ../..
podcast gui --project /path/to/my_episode/episode.sharecut
```
Release wheels include the web build (the `release-wheel` workflow runs `npm run build` before `uv build`). A wheel built without it makes `podcast gui` warn at startup and `/` explain how to build it and set `PODCAST_GUI_DIST` ([docs/setup.md](docs/setup.md#web-build-in-wheels)). Hot reload: `podcast gui --project β¦ --dev --no-open` plus `cd gui/web && npm run dev`. Agents: MCP `open_gui_tool` / skill `podcast-open-gui` (or `podcast gui --background`). Details: [docs/gui-integration.md](docs/gui-viewer.md#gui-viewer), [docs/setup.md](docs/setup.md#read-only-gui-viewer).
For the development-only UI component catalog, run `cd gui/web && npm ci && npm run storybook`; see [docs/design-system.md](docs/design-system.md) for publishing setup.
A clean clone needs no relay, account, object store, CDN, or signing credentials
for local editing. Before enabling collaboration or building a downstream desktop
distribution, validate only that modeβs configuration:
```bash
podcast config check --mode local
podcast config check --mode self-hosted --relay-config config/relay.example.yaml
podcast config check --mode distributor --distribution-profile /path/to/distribution.json
```
Runtime secrets belong in environment variables or
`~/.config/podcast_mcp/relay.yaml`; public desktop identity belongs in a validated
distribution profile. See [docs/setup.md](docs/setup.md#configuration-boundary).
Edit transcription vocabulary with `podcast transcript context set`: pass
`--project PATH --term NAME` or remove entries with `--remove-term NAME` / `--remove-guest-name NAME`.
Host MCP agents can read and replace it with revision checks. See the
[transcript workflow](docs/transcript-workflow.md).
## Documentation
- [ShareCut Studio Extensions](docs/extensions.md) β public plugin SPI (absent = no render); [seams](docs/extension-seams.md)
- [Host-online relay](docs/host-online-relay.md) β Docker share edge, tunnel, **capability-scoped remote MCP** (via the FOSS collaboration extension)
- [Share tokens and registry backups](docs/share-tokens.md#backup--restore) β create a new private backup with `podcast review backup-registry`; `--dest` requires an unused name in an existing trusted private directory.
- [Recording session (design)](docs/recording-session.md) β record links, full-quality recording on each device, mix-minus monitor, consent
- [UX onboarding pack](ux/README.md) β shareable brief, screens, glossary, backlog ([live site](https://ux.sharecut.studio/); [See the UI](https://ux.sharecut.studio/#/demo))
- [UI philosophy](docs/ui-philosophy.md) β trust-first beta design principles for automation, recovery, and the free core workflow
- [Communication philosophy](docs/communication-philosophy.md) β voice, terminology, control placement, and the mobile ergonomics checklist for user-facing UI
- [Interaction system](docs/interaction-system.md) β one path per interaction (selection, targets, menus, sheets, feedback, keyboard and touch equivalents), the registries, and the checklist a new interaction passes
- [Setup](docs/setup.md) β install, extras, optional downloads, MCP, bootstrap, play, GUI
- [Architecture](docs/architecture.md) β layers and timebase
- [Contributing](docs/contributing.md) β where new code goes; [Git workflow](docs/contributing.md#git-workflow) (feature branch β PR β the base branch in `config/branches.json`)
- [Agent instructions](AGENTS.md) β SOLID/DRY, tests-as-you-go, docs in sync
- [Episode format v2](docs/episode-format-v2.md) β canonical `episode.sharecut` (see also [project-format.md](docs/project-format.md))
- [Multitrack ingest & alignment](docs/multitrack-ingest.md) β raw files β one track per speaker
- [Transcript workflow](docs/transcript-workflow.md) β reconcile β precorrect β refine β audition
- [Natural language editing](docs/nl-editing.md)
- [Inaudible cut boundaries](docs/inaudible-cuts.md)
- [Edit history / undo-redo](docs/history.md)
- [Session sync](docs/session-sync.md) β agent β DAW transport
- [GUI integration](docs/gui-integration.md) β viewer API, layers, live reload
- [Social clips](docs/social-clips.md)
- [Timeline comments](docs/timeline-comments.md) β review feedback + action items (MCP/CLI/DAW)
- [Pipeline](docs/pipeline.md)
- [Testing](docs/testing.md)
- [CI workflow](.github/workflows/test.yml) defines the frontend browser matrix
and its job timeouts, including the Chromium and WebKit compatibility jobs.
- Editor profiling: `npm --prefix gui/web run profile:remaining` runs disposable
workload profiles; `profile:compare` freezes or applies local diagnostic budgets;
`make profile-seek-trim OUT=/tmp/seek-trim` profiles ruler seek and clip trim.
See [the profiling commands and limits](docs/testing-e2e.md#large-project-browser-profile-opt-in).
- [Roadmap](ROADMAP.md)
Diagnostics and report-submission orchestration live in
[`services/support/`](src/podcast_mcp/services/support/); pipeline execution,
configuration, and component bootstrap live in
[`services/pipeline/`](src/podcast_mcp/services/pipeline/). Contributor import
rules are in [Contributing](docs/contributing.md#service-context-imports).
## Support
Bugs: [GitHub Issues](https://github.com/calebn/sharecut-studio/issues/new?template=bug_report.yml). Attach a sanitized diagnostics zip from **Home β ShareCut app menu β Help β Report a problem β Export** or `podcast doctor --bundle` (writes `~/Downloads/sharecut-diagnostics-<UTC>-<nonce>.zip`). Nothing is uploaded automatically β there is no telemetry. Do not attach episode audio or project JSON. Minted shares may transit the relay; GitHub issue attachments are public. Detail: [docs/setup.md Β§ Troubleshooting](docs/setup.md#troubleshooting).
## Privacy
Beta policy (local audio unless you mint a share; relay is a pass-through that does not store audio but share audio/media may transit while the share is active; no telemetry): [sudo.science/privacy.html](https://sudo.science/privacy.html).
## Play audio (listen while developing)
```bash
podcast play --project tests/fixtures/aligned_dialogue/episode.sharecut \
--source processed:reference --start 0 --end 15 # edits + FX (stem or segment render)
podcast play --project ... --source track:guest --start 0 --end 15 # raw alignment
podcast play --project ... --compare --start 18 --end 28 # alignment check
podcast play --project ... --query documented # after transcript is seeded
podcast play --project ... --dry-run # extract WAV only; see "tier" in JSON
```
## Testing
Tests run with a **95% minimum coverage** gate (see [docs/testing.md](docs/testing.md)):
```bash
make test # full suite + coverage gate (parallel)
make test-fast # quick inner loop, no coverage
make e2e # aligned_dialogue fixture; see docs/e2e-fixture-manual.md
```
GUI frontend unit tests (session dedupe, etc.): `cd gui/web && npm test`.
GUI browser tests use `npm --prefix gui/web run test:e2e`; its wrapper owns private
registry and identity state. `make ux-demo-screens` captures host and guest views
from a disposable copy of the existing showcase fixture.
## License
ShareCut Studio is licensed under the GNU Affero General Public License, version 3 or later (AGPL-3.0-or-later). See [LICENSE](LICENSE).
TDQS
Scored across 218 tools
Descriptions work unusually hard to draw boundaries (e.g. "prefer set_clip_join_tool over set_join_mode_tool", "not preview_inaudible_cut_tool", "use ripple_delete_tool instead"), which rescues many pairs. However, at 218 tools there are large near-duplicate families β five `cut_*` staging tools, `ripple_delete_tool` vs `ripple_delete_text_tool` vs `delete_clips_tool` vs `propose_range_cut_tool`, `propose_edits`/`apply_edits`/`approve_edits_tool`/`apply_suggested_actions_tool`, and singular/plural pairs like `set_clip_fade_tool` vs `set_clips_fade_tool` β so misselection remains a real risk.
Most names are verb_noun (list_clips_tool, add_chapter_tool, render_preview), but the `_tool` suffix is applied inconsistently across the set: `propose_edits`, `apply_edits`, `history_undo`, `feed_read`, `record_stop_tool`, `get_transcript`, `export_transcript` coexist with `*_tool` variants of the same families. Some families also mix prefixes (history_undo vs history_status_tool, track_add vs track_add_empty_tool), which is readable but not predictable.
218 tools for a single podcast-production server is a severe mismatch against the 3-15 guidance; an agent cannot hold this surface in context or discover the right tool reliably. Even though the domain is genuinely broad, the count is well past any reasonable scoping, and several tools are marginal variants of each other.
Coverage is exhaustive for the domain: ingest/recording rooms, transcription and word-level correction, gating/bleed/audibility, cut and ripple editing, fades/joins/gain, effects, rendering and export, chapters, comments/review, review shares, feeds, segment and kit libraries, social clips, speakers, history/undo, and config. Nearly every lifecycle (create/read/update/delete/undo) has an operation, with few dead ends.