TalkEdit/.github/copilot-instructions.md

TalkEdit Copilot Instructions (Living Project Context)

Purpose: give AI assistants immediate, accurate context for this repository and define what must be kept in sync when the project evolves.

How To Use This File

• This is a workspace instruction file for VS Code Chat/Copilot.
• Treat this as the first source of truth for architecture and workflow expectations.
• If your code changes make any section outdated, update this file in the same change.

Project Snapshot

• Name: TalkEdit
• Product: local-first, AI-powered, text-based audio/video editor.
• Primary runtime today: Tauri + React frontend + Python FastAPI backend.
• Legacy/transition artifacts may still exist (for example Electron paths/APIs), but default implementation direction is TalkEdit + Tauri.

Tech Stack

• Frontend: React 19, TypeScript, Vite, Tailwind, Zustand.
• Desktop bridge: Tauri API with compatibility shim exposing window.electronAPI in frontend/src/lib/tauri-bridge.ts.
• Backend: FastAPI + Uvicorn (backend/main.py) with routers in backend/routers and core services in backend/services.
• Media tooling: FFmpeg for edit/export and codec operations.
• AI tooling: WhisperX/faster-whisper for transcription; provider layer supports OpenAI/Anthropic/Ollama.

Code Map

• frontend/src/components: editor UI (player, transcript, waveform, settings, export, AI panel).
• frontend/src/store: Zustand state (editorStore, aiStore).
• frontend/src/hooks: keyboard/video sync behavior.
• backend/routers: API surface (/transcribe, /export, /ai/*, /captions, /audio/*).
• backend/services: heavy operations (transcription, captioning, diarization, video editing, cleanup).
• shared/project-schema.json: saved project schema contract.
• src-tauri: Rust/Tauri host code and app configuration.

Run And Build (Preferred)

• Frontend dev: npm run dev
• Backend dev: npm run dev:backend
• Tauri dev: npm run dev:tauri
• Tauri build: npm run build:tauri

Use project virtualenvs where available (.venv312, .venv, or venv) for backend execution.

Working Conventions

• Keep router files thin; put heavy logic in backend/services.
• Preserve response compatibility for existing frontend callers unless task explicitly allows API breakage.
• Keep frontend bridge compatibility stable: if desktop APIs change, update both Tauri-side implementation and the window.electronAPI shim contract.
• Prefer small, focused edits over broad refactors.

Known Risk Areas

• Startup/rendering on Linux WebKit can regress when reintroducing remote fonts/CSP allowances; prefer local font assets.
• Media URL handling between project load paths should remain consistent to avoid format-specific regressions (especially WAV/MP3 behavior).
• Export pipeline changes must preserve caption modes (none, sidecar, burn-in) and audio enhancement behavior.

Update Rules (Important)

When a task changes architecture, app wiring, commands, API shape, project schema, or major conventions, update this file before finishing.

Always update these sections if affected:

• Project Snapshot
• Tech Stack
• Code Map
• Run And Build (Preferred)
• Known Risk Areas

If behavior changed significantly, add a short note under a new Recent Changes section with:

• Date (YYYY-MM-DD)
• What changed
• What future edits should preserve

Assistant Behavior For This Repo

• Validate assumptions against current files before editing.
• Prefer existing patterns in neighboring files over introducing new patterns.
• Call out uncertainty explicitly when code and docs disagree.
• If you discover stale docs, fix them as part of the same task when reasonable.