naqashafzal/ai-content-studio

1. Purpose and entry points

Nullpk AI Content Studio is a local Python desktop application that turns a user topic into publishable YouTube-oriented media: research, script, narration, visuals, captions, metadata, and optional social uploads. The primary executable entry point is main.py; run.sh and run.bat are platform launch wrappers. The GUI is CustomTkinter-based.

Paths: main.py, run.sh, run.bat

2. UI orchestration boundary

The desktop UI collects the topic, style, generation options, credentials/settings, and publishing choices. It initiates the pipeline and presents generated artifacts for review, especially SEO metadata and publishing actions. UI interaction should remain separated from long-running network/media work to preserve responsiveness.

Paths: main.py, pipeline.py, config.py

3. Pipeline coordinator

pipeline.py is the lifecycle coordinator. It sequences conditional stages according to selected content format and options: research, script generation/revision, voice/audio, visual generation, assembly, captions, thumbnails, SEO, and upload. It is the main control-flow boundary between user intent and artifact production, and should own stage status, intermediate outputs, and failure propagation.

Paths: pipeline.py, main.py

4. AI agents: research, writing, and content planning

agents.py contains the generative-AI roles that transform a topic and gathered context into research, scripts, fact-check/revision output, and likely SEO-oriented content. Gemini is the core text and TTS model family. Agent outputs become structured or textual inputs to downstream narration, visual selection, and metadata stages.

Paths: agents.py, pipeline.py, api_clients.py

5. External API integration layer

api_clients.py centralizes calls to external providers: Google Gemini/Google Search grounding, Vertex AI image/video generation, NewsAPI headlines, and optional WaveSpeed video generation. This is the critical provider boundary for authentication, request/response normalization, retries, and service-specific failures.

Paths: api_clients.py, config.py, agents.py

6. Media production and artifact assembly

The pipeline converts scripts into multi-speaker TTS/audio, optionally mixes background music, produces AI visuals, creates thumbnails, and renders the final video. FFmpeg is the essential local rendering dependency; Whisper generates speech timing and pysubs2 supports styled ASS subtitles. temp_preview.ass is an example/generated subtitle-preview artifact, while cyberpunk.json is likely a visual/style preset consumed during generation.

Paths: pipeline.py, temp_preview.ass, cyberpunk.json

7. Publishing and runtime dependencies

The final artifact path includes captioned video, thumbnail, SEO title/description/tags, chapter timestamps, and direct YouTube/Facebook publishing. YouTube requires local OAuth desktop credentials (client_secrets.json, user-provided); API keys and GCP project/location are persisted through the application configuration. Runtime requires Python 3.10+, FFmpeg on PATH, Google/Vertex credentials, and packages declared in requirements.txt.

Paths: config.py, pipeline.py, requirements.txt