Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.
podcli Studio: Phase 1 Implementation Plan
Major release groundwork. Full design (13 decisions) lives in the session memory file
project_studio_dashboard_design.md. This plan covers Phase 1 only: the studio shell, library + per-clip edit pages, and CLI parity. No YouTube/analytics (Phase 2), no semantic learning (Phase 3).
Guiding constraints: open source; clean, correct, minimal extra code; .podcli/ is the
shared on-disk contract; Python is the engine + history writer, web/MCP are thin shells.
Stack decision: Vite + React Router replaces the single-file CDN-React src/ui/public/index.html.
Phase 0: Discovery (DONE, facts to build on)
UI / build
- No bundler today.
src/ui/public/index.html(~1880 lines) loads React 18.2 + ReactDOM + babel-standalone via CDN, all app code in one<script type="text/babel">. CSS:public/css/styles.css. Other pages:config.html,integrations.html,knowledge.html. - Express serves statics:
app.use(express.static(join(__dirname, "public"))),src/ui/web-server.ts:197. Port 3847 (web-server.ts:52). No SPA fallback route today. - Build:
"build": "tsc && cp -r src/ui/public dist/ui/"(package.json)."type":"module", target ES2022, module ESNext,rootDir ./src,outDir ./dist, nojsxconfigured (public/ is not part of tsc build). - Stable API surface the new UI consumes:
/api/history,/api/outputs,/api/ui-state(GET/POST, MCP↔UI bridge),/api/events(SSE),/api/preview/:f,/api/stream-source, plus the full upload→transcribe→suggest→create/batch flow.
Data layer
ClipHistoryEntry(src/models/index.ts:200-213):id, source_video, start_second, end_second, caption_style, crop_strategy, logo_path?, title, output_path, file_size_mb, duration, created_at. Nocontent_type,score, transcript, or youtube fields.src/services/clips-history.ts:load / save / record / findDuplicate / list / getBySource.record(entry: Omit<ClipHistoryEntry,"id"|"created_at">). Writespaths.clipsHistory=${home}/history/clips.json.- 5
record()call sites:web-server.ts:600(create-clip),:729(batch-clips),:1804(davinci export);server.ts:666(MCP create_clip),:908(MCP batch_create_clips). content_typeoriginates insuggest-clips.handler.ts:123; the suggestion (withcontent_type) is resolved atcreate-clip.handler.ts:128-137; transcript words available atcreate-clip.handler.ts:152, but neither is threaded intorecord().- Python does NOT read/write clips.json today.
backend/config/paths.py:59knows the path; nothing uses it. No Python history module exists. - Paths agree across
src/config/paths.tsandbackend/config/paths.py.
CLI / Python
backend/cli.py: argparse withif/elif args.commanddispatch (main()~line 2854+). Existing subcommands:process, presets, assets, thumbnails, swap-thumbnail, corrections, knowledge, config.- Copy templates: read =
cmd_assets(2026-2078), write =2361-2451). Both print ANSI text, import service modules locally,cmd_knowledge(sys.exit(1)on error.swap-thumbnail(~2177-2318) finds a clip by file path, not clips.json. - Config loaded via
from config.paths import paths(cli.py:43). Service modules live inbackend/services/(pattern to mirror:corrections.py). - CLI = human ANSI text, no
--json. The JSON task-runner is separate (backend/main.pyemit_result+TASK_HANDLERS), used byPythonExecutor. TheclipsCLI commands use the ANSI/human contract. PythonExecutor.execute(taskType, params)(src/services/python-executor.ts) spawnsbackend/main.py, JSON over stdin/stdout. (Relevant to Phase 2; Phase 1 CLI runs cli.py directly.)
Concurrency note (accepted constraint): clips.json has no file locking. Single-user localhost tool; TS writes on render, Python writes on clips edit, not concurrent in practice. Do not add locking (over-engineering). Both writers must preserve unknown fields on rewrite (read-modify-write, never reconstruct).
Phase 1A: Data foundation (schema + Python history writer)
Lowest risk, no UI. Establishes the shared contract everything else builds on.
What to implement
- Extend
ClipHistoryEntryinsrc/models/index.ts:200-213with optional fields (additive, no migration):content_type?: string; // carried from SuggestedClip at record time transcript_slice?: string; // packed/plain text of the clip's words, captured at render time youtube_video_id?: string; // Phase 2, declared now so the schema is stable metrics?: { // Phase 2: declared now, never written in Phase 1 views?: number; retention?: number; // averageViewPercentage 0-100 ctr?: number; // impressionsClickThroughRate 0-100 impressions?: number; fetched_at?: string; // ISO }; - Thread
content_type+transcript_sliceinto the TS record calls where they are in scope:- In
create-clip.handler.ts, the resolvedsuggestion(hascontent_type) andtranscriptWords(line 152) are both available. Build atranscript_slicestring (join the words whose timestamps fall in[start_second, end_second]) and surface both on the handler's return so the web/MCP record sites can pass them. - Update the 5 record() sites to pass
content_typeandtranscript_slicewhen available (omit otherwise; they're optional). Batch/davinci sites: thread per-clipcontent_typeif the batch spec carries it; otherwise leave undefined. Do not invent data: only pass what is genuinely in scope.
- In
- Create
backend/services/clips_history.pymirroringcorrections.pystructure. Functions:
Useload_clips_history() -> list[dict] # read paths["clipsHistory"], [] if missing/bad save_clips_history(entries) -> str # mkdir -p, json.dump indent=2 ensure_ascii=False list_clips(limit=50) -> list[dict] # entries[-limit:][::-1] get_clips_by_source(video_path) -> list[dict] # basename match, reversed find_clip(clip_id) -> dict | None # exact id, also accept 8-char prefix match update_clip(clip_id, **fields) -> dict # read-modify-write, preserve unknown keys, return updatedfrom config.paths import pathsandpaths["clipsHistory"]. Preserve unknown fields (read-modify-write) so a TS-writtenmetricsblock is never clobbered by a Python edit. - Document the schema as the cross-language contract: add
docs/clips-schema.md(or a header comment block inclips_history.py) listing every field, type, who writes it (TS-render / Python-edit / Phase-2), and the "preserve unknown fields" rule.
Documentation references
- Extend interface:
src/models/index.ts:200-213. - Record sites to update:
web-server.ts:600,729,1804;server.ts:666,908. - Where content_type/transcript are in scope:
create-clip.handler.ts:128-137,152. - Python service pattern to copy:
backend/services/corrections.py; path:backend/config/paths.py:59.
Verification checklist
-
npm run build(tsc) passes with the extended interface. - Render a clip via the web UI → the new
clips.jsonentry includescontent_typeandtranscript_slice(when a suggestion was used). -
python -c "from backend.services.clips_history import list_clips; print(list_clips(3))"reads the same file TS wrote. - Python
update_clipthen TSload()→ unknown fields survive both round-trips (write ametricsstub by hand, edit title in Python, confirmmetricsstill present).
Anti-pattern guards
- ❌ No new entities/tables, no migration script. Fields are optional, so old entries stay valid.
- ❌ Do not rewrite clips.json by reconstructing objects field-by-field (drops unknown keys). Read-modify-write only.
- ❌ Do not add file locking.
- ❌ Do not fabricate
content_type/transcript_slicewhere the source data isn't actually in scope: leave undefined.
Phase 1B: CLI clips subcommands
Delivers CLI parity for history + re-iteration entry point. Depends on 1A's Python service.
What to implement
- Register the
clipssubparser incli.py main()(besideknowledge), following the existingadd_parser/add_subparserspattern:clips list [-n/--limit N]clips edit <clip_id> [--title T] [--caption-style S] [--notes ...](metadata-only edits per design: edit → save → latest)clips reopen <clip_id>: hydrate.podcli/ui-state.jsonfrom the history entry so the web Workspace opens with that clip loaded (see below).- Add
elif args.command == "clips": cmd_clips(args)to dispatch.
- Implement
cmd_clips(args)using thecmd_assets/cmd_knowledgeANSI template:list: print id (8-char), title, source basename, created_at, duration; showcontent_typeif present.edit:find_clip→ apply provided fields →update_clip. Error +sys.exit(1)if not found.reopen: read the entry; write a single-suggestionui-state.json,videoPath = source_video, a one-itemsuggestionsarray reconstructed from the entry (title, start_second, end_second, duration, content_type, preview_text = transcript_slice),phase = "reviewing". This is the CLI→UI bridge over the shared.podcli/contract. Print confirmation + the URLhttp://localhost:3847/episode?...(or instruct to open the studio).
reopensemantics are metadata-only in Phase 1: it loads the clip back into the editing surface; it does not auto-re-render. (Re-render is a save action in the UI / a future flag.)
Documentation references
- Subparser + dispatch:
cli.py main()(~2862-3044). - Read handler template:
cmd_assets(2026-2078). Write handler template:2361-2451).cmd_knowledge( - ui-state shape to write:
UIStateinsrc/models/index.ts:106-121(videoPath, suggestions, phase).
Verification checklist
-
python backend/cli.py clips listprints recent clips from the same clips.json the UI shows. -
clips edit <id> --title "X"→clips listreflects it AND the web UI/api/historyshows the new title. -
clips reopen <id>writes ui-state.json; opening the studio loads that clip into the Workspace. - Editing a clip in Python preserves its
metrics/unknown fields (re-run the 1A round-trip check).
Anti-pattern guards
- ❌ Don't emit JSON from the CLI (human ANSI contract), match existing subcommands.
- ❌ Don't reach into TS to record; write clips.json via the Python service from 1A.
- ❌
reopenmust not trigger a render in Phase 1.
Phase 1C: Vite + React Router scaffold (parity with current UI)
Stand up the build app and port the existing editor into a route, preserving all working functionality before adding new pages.
What to implement
- New client source dir
src/ui/client/(Vite root). Files:index.html(Vite entry, no CDN),main.tsx(mounts<RouterProvider>),App.tsx(layout shell + nav),routes/andcomponents/. - Add deps (devDeps):
vite,@vitejs/plugin-react,@types/react,@types/react-dom. Deps:react,react-dom,react-router-dom. (React leaves the CDN.) src/ui/client/vite.config.ts:root: src/ui/client,plugins:[react()],build.outDir: ../../../dist/ui/public+emptyOutDir: true,server.proxymapping/api→http://localhost:3847.- Client tsconfig
src/ui/client/tsconfig.jsonwithjsx: "react-jsx", DOM libs. Excludesrc/ui/clientfrom the roottsconfig.jsonso the nodetscbuild (server) and the Vite build (client) don't fight. Root tsconfigexcludeadds"src/ui/client". - Router (
react-router-dom) with routes:/→StudioHome(Phase 1D)/episode(and/episode/:source?) →EpisodeWorkspace(the ported existing editor)/clip/:id→ClipDetail(Phase 1D)
- Port the existing editor from
public/index.htmlintoroutes/EpisodeWorkspace.tsx+ extracted components (LivePhonePreview,TikTokWireframe,PhoneCaptionBody,SpecRecap,McpHints). Mostly mechanical: move JSX out of the babel<script>, replace CDN globals (const {useState}=React) with real imports, keep theapi()fetch helper and theSTYLE_CONFIGSmap. Reusepublic/css/styles.css(import it). - Express: serve the built SPA + add a fallback route. Keep
express.staticatweb-server.ts:197(now serving Vite output indist/ui/public). After all/apiroutes, add an SPA fallback:app.get("*", (req,res)=> res.sendFile(join(__dirname,"public","index.html"))), guard so it never shadows/api/*or static assets. - Update build/dev scripts in
package.json:"build": "vite build --config src/ui/client/vite.config.ts && tsc && cp -r src/ui/public/css dist/ui/public/css && cp src/ui/public/*.png dist/ui/public/"(Vite emits HTML/JS todist/ui/public; still copy non-bundled css/images, or import CSS through Vite and drop the copy)."ui:dev": "vite --config src/ui/client/vite.config.ts"(client) alongside existing"ui": "tsx src/ui/web-server.ts"(server). Document running both in dev.
- Legacy pages: leave
config.html/integrations.html/knowledge.htmlas-is for Phase 1 (link out to them), OR fold into routes later. Do not deletepublic/index.htmluntil parity is confirmed; then remove.
Documentation references
- Static serving to preserve/extend:
web-server.ts:197; listen:web-server.ts:~1862. - Components + STYLE_CONFIGS +
api()to port:src/ui/public/index.html(App ~554, LivePhonePreview ~358, TikTokWireframe ~175, PhoneCaptionBody ~275, SpecRecap ~471, McpHints ~499, api() ~58, STYLE_CONFIGS ~114). - Build script to replace:
package.json"build".
Verification checklist
-
npm run ui:dev+npm run ui→ app loads on Vite dev server,/apiproxied, full upload→transcribe→suggest→create flow works identically to the old UI. -
npm run build→dist/ui/public/index.htmlis the Vite output;npm run ui:prodserves it on 3847; deep-linking/episodeand refresh work (SPA fallback). - No CDN
<script>for React/Babel remains in the served HTML. -
git grep babel-standalonereturns nothing in the new client.
Anti-pattern guards
- ❌ Don't rewrite editor logic: port it (move + swap imports). Behavior parity first, cleanup later.
- ❌ Don't let
tsctry to compile the client (must be in root tsconfigexclude). - ❌ SPA fallback must be registered AFTER api routes and must not intercept
/api/*. - ❌ Don't break the
/api/ui-stateMCP↔UI bridge: the Workspace must still read/write it (this is howclips reopenhands off).
Phase 1D: Studio Home (library) + Clip Detail (edit page)
The new surfaces. Depends on 1A (fields), 1B (edit path), 1C (router/shell).
What to implement
StudioHome(/): the library:- Fetch
/api/history(and/api/outputsfor file existence). Group into episodes bysource_videobasename (mirrorgetBySourcelogic client-side, or add a thin/api/episodesendpoint that callsclips-history.getBySourcegrouping; prefer reusing existing/api/historyto keep code minimal). - Episode cards: source name, clip count, created range, status. Recent-clips rail. An action rail up top driven by clip state ("N clips rendered", "Episode X in review"), derive from existing data with no new backend.
- "+ New Episode" →
/episode(fresh editor).
- Fetch
ClipDetail(/clip/:id): the per-clip edit page (design decision: edit → save → latest, no version stacks):- Load the clip (from
/api/historyby id, or a small/api/clip/:idthat callsfind_clip). Show preview (/api/preview/:filenamefromoutput_path), transcript_slice, content_type, settings. - Editable fields: title, caption style, thumbnail, cut timing. Save:
- Metadata-only edits (title) → POST to a thin endpoint that calls the same Python
update_clip(viaPythonExecutoror a small route) so TS and CLI share one writer. (Minimal: addupdate_cliptask tobackend/main.pyTASK_HANDLERS reusing 1A's service, exposed as/api/clip/:idPATCH.) - Caption/timing change → triggers a re-render through the existing create-clip flow, then updates the entry (save = latest).
- Thumbnail change → reuse existing
swap-thumbnailcapability (already in cli.py / thumbnail service).
- Metadata-only edits (title) → POST to a thin endpoint that calls the same Python
- "Reopen in editor" → navigates to
/episodewith this clip hydrated (same handoff as CLIreopen).
- Load the clip (from
- Keep it data-minimal: prefer reusing
/api/history,/api/preview,/api/outputs,/api/ui-stateover new endpoints. Add a backend route only where a write must go through the shared Python writer (the clip edit).
Documentation references
- Grouping logic:
clips-history.ts getBySource(basename match). - Existing endpoints to reuse:
/api/history,/api/outputs,/api/preview/:f,/api/ui-state. - Edit writer: Phase 1A
backend/services/clips_history.py update_clip; thumbnail:cmd_swap_thumbnailmechanics (cli.py ~2177-2318).
Verification checklist
- Home lists episodes grouped by source with correct clip counts.
- Clicking a clip opens
/clip/:idwith preview + metadata. - Editing a title in the UI persists via the same Python writer the CLI uses (verify with
python backend/cli.py clips list). - Changing caption style re-renders and the entry reflects the latest output.
- "Reopen in editor" loads the clip into the Workspace (same result as
clips reopen).
Anti-pattern guards
- ❌ No version stacks/trays: one current state per clip.
- ❌ Don't add a second history writer in TS for edits: route edits through the Python
update_clipso there is one source of truth. - ❌ No YouTube/metrics UI (Phase 2),
metrics/youtube_video_idexist in the schema but are not surfaced or written here.
Final Phase: Verification
- Build & run:
npm run buildclean (tsc + vite);npm run ui:prodserves the SPA on 3847; deep links + refresh work. - Parity: full upload→transcribe→suggest→create/batch flow works in the new UI identically to the removed
index.html. - Cross-language contract: create a clip in the UI →
python backend/cli.py clips listshows it withcontent_type/transcript_slice;clips editfrom CLI → UI reflects it; a hand-writtenmetricsblock survives a Python edit (preserve-unknown-fields). - CLI parity:
clips list/edit/reopenall function headless. - Anti-pattern grep: no
babel-standalone/CDN React in served HTML; client excluded from root tsconfig; SPA fallback after api routes; single history writer for edits. - Tests: run existing suite (299 tests baseline); add focused tests for
clips_history.py(round-trip, preserve-unknown-fields, find/update) and for the extendedClipHistoryEntryrecording.
Suggested execution order
1A → 1B → 1C → 1D → Final. 1A/1B are independent of the UI and ship value (CLI history) immediately; 1C is the big migration; 1D adds the new surfaces on the shell. Each sub-phase is self-contained for a fresh context.