1 Verify your Mac is pipeline-ready ~2 min

Open Terminal (or the integrated terminal in VS Code) and paste this. Every line should return a version number — not "command not found."

python3 --version && ffmpeg -version | head -1 && git --version && node --version

brew install python@3.11   # if python3 not found
brew install ffmpeg        # if ffmpeg not found
brew install git           # if git not found
brew install node          # if node not found

2 Run the Bootstrap Prompt in Claude Code ~30–45 min

This is the fastest setup path. Joe has a file called MIKE-BOOTSTRAP-PROMPT.md — ask him for it. Then:

3 Get your API keys ~15 min

Paste each key into the .env file the bootstrap created. Never commit it — it's already in your .gitignore.

4 Get the pipeline scripts from Joe once

The bootstrap builds the structure but the production engine (produce.py, make_short.py, build_timing.py) lives in Joe's repository. Ask Joe to either add you as a GitHub collaborator or zip the 06_pipeline/explainer-engine/ folder. Drop those files into the matching folder in your project.

cd ~/Developer/VivereChannels
pip3 install -r requirements.txt

# Verify the pipeline loads:
cd 06_pipeline/explainer-engine
python3 produce.py --help

5 Stage 0 — Define your channel do this with Joe, Session 2

Everything downstream — voice, visuals, scripts, hooks — is derived from your Stage 0 answers. Don't rush this. Read Stage 0 · Pre-Build Decisions in full, then sit down with Joe to lock your answers. The 8 questions:

Your Pilot Episode Checklist

Track your progress from setup to first upload. Nothing goes live until Joe approves the pilot.

These are frameworks — not final brand decisions. The name, mascot, palette, and voice for each would be developed in Stage 0–2 of the build process.

1A. Create brand.json

Every channel has exactly one brand.json. This file controls what the pipeline produces — voice settings, art model, image style, output directory. Copy the template and fill every field.

{
  "channel": "your-channel-slug",
  "name": "Full Channel Name",
  "voice": {
    "voiceId": "ELEVENLABS_VOICE_ID_GOES_HERE",
    "stability": 0.5,
    "similarity_boost": 0.75,
    "style": 0.0,
    "use_speaker_boost": true
  },
  "art": {
    "model": "fal-ai/flux-pro/v1.1",
    "aspect_ratio": "2:3",
    "style_suffix": "YOUR BRAND STYLE SUFFIX — append this to every image prompt"
  },
  "music": {
    "mood": "describe the music mood here",
    "lufs": -26
  },
  "publish_dir": "C:/Users/USERNAME/Desktop/Developer/Media Channels/CHANNEL NAME/UPLOAD READY"
}

1B. Create the Brand Context File

Copy 00_context/_channel-brand-template.md to 00_context/YOUR-SLUG-brand.md. This is the human-readable brand bible — used when writing scripts, generating assets, and briefing contractors.

Must include: palette (hex values), mascot brief, voice register description, art direction notes, music brief, content guardrails, and at least 3 sign-off catchphrases (rotate — never repeat back-to-back).

1C. Register in channels.json

The central registry at 06_pipeline/channels.json controls every automated workflow. Add one block per channel:

"your-slug": {
  "name":               "Full Channel Name",
  "brand":              "your-slug",
  "media_dir":          "Channel Folder Name",
  "handle":             "@channelhandle",
  "niche":              "topic / niche",
  "youtube_channel_id": "",
  "youtube_category":   "27",
  "publish_time":       "12:00",
  "blotato":            { "youtube": "", "tiktok": "", "instagram": "" },
  "status":             "setup",
  "ep_prefix":          "XX"
}

YouTube category codes: 27 = Education · 24 = Entertainment · 26 = Howto & Style · 22 = People & Blogs
Status lifecycle: setup → ready → live

1D. Create the Media Folder

Media Channels/
└── Channel Folder Name/
    ├── Brand Assets/
    │   ├── brand.json          (copy from channels/SLUG/brand.json)
    │   ├── MASCOTS.md          (mascot generation prompts + pose library)
    │   └── music/              (music beds + outro sting files)
    ├── UPLOAD READY/           (final MP4s — pipeline writes here)
    ├── Pilot Draft/            (renders before approval)
    └── social_posts/           (static social image output)

2A. Define the Mascot in Writing First

Write a complete mascot brief before generating a single image. Every downstream prompt references this brief. If the brief is vague, the images will be inconsistent.

2B. Generate the Pose Library

Generate all poses from the same base description before any video production begins. One drifting detail in the first prompt will cascade through every future image if you don't lock the library first.

2C. Prompt Structure for Consistency

[ART STYLE] of [CHARACTER FULL DESCRIPTION with exact hex values],
[POSE DESCRIPTION — specific action],
[BACKGROUND — on-brand setting],
[BRAND STYLE SUFFIX from brand.json],
negative: [list what NOT to include]

2D. Save & Document

Save all mascot images to Media Channels/Channel Name/Brand Assets/mascot/.
Naming: mascot_idle.png, mascot_hero.png, mascot_action_[description].png
Document the full generation prompt, seed, and tool version in Brand Assets/MASCOTS.md.

3A. YouTube Channel

1. 1
   Create the channel

   youtube.com → Google account avatar → Create a channel. Use the exact channel name from Stage 0.
2. 2
   Claim the handle

   Settings → Channel → Handle. Verify the @handle is available before you finalize the channel name. Check TikTok and Instagram availability at the same time.
3. 3
   Upload brand assets

   Profile picture: mascot or channel icon, square, 800×800 min. Banner: 2560×1440, tagline in the safe area (the center 1235×338 area is always visible).
4. 4
   Write the About section

   2–3 sentences: what the channel is, what viewers should expect, how often. Include the owned site URL if one exists. No keyword stuffing.
5. 5
   ⚠ Critical: Set audience to "Not made for kids"

   Settings → Channel → Advanced Settings → Audience → "No, it's not made for kids." This unlocks full monetization features. Missing this step will cost you money.
6. 6
   Copy the YouTube Channel ID

   Settings → Channel → Advanced Settings → Channel ID (starts with UC...). Paste into channels.json → youtube_channel_id.

3B. TikTok & Instagram Accounts

Create both with the same @handle as YouTube. Switch to a Business or Creator account on Instagram (required for scheduling via third-party tools). Use the same profile picture across all three platforms.

3C. Connect to Blotato (Cross-Post Scheduler)

Blotato is the scheduling layer. Every channel's YouTube, TikTok, and Instagram accounts must be connected before any automated or scheduled posting works.

1. 1
   Add each account in Blotato

   Blotato → Accounts → Add Account → select platform → OAuth authorize. Repeat for YouTube, TikTok, and Instagram.
2. 2
   Record the Blotato account IDs

   After connecting, click each account in Blotato — the numeric ID appears in the account detail or URL. These IDs are what the automation uses to target the right account.
3. 3
   Update channels.json

   Fill in the blotato block: "blotato": {"youtube": "12345", "tiktok": "12346", "instagram": "12347"}

3D. Google Cloud / YouTube API (for auto-upload)

1. 1
   Create a Google Cloud project

   console.cloud.google.com → New Project. One project supports ~3 channels (YouTube API quota). Create additional projects as you scale past that.
2. 2
   Enable YouTube Data API v3

   Library → search "YouTube Data API v3" → Enable.
3. 3
   Create OAuth credentials

   Credentials → Create Credentials → OAuth 2.0 Client ID → Desktop app → Download JSON → rename to client_secret.json → place in the explainer-engine folder.
4. 4
   Authorize (one-time per channel)

   Run python yt_autopublish.py — a browser window opens, sign in to the channel's Google account, authorize. Token is saved automatically for future runs.

4A. Script the Episode

Copy 02_scripts/_script-template.md to 02_scripts/XX01-topic-slug.md. The episode ID format is: prefix + sequential number + topic slug (e.g. S001-why-ice-floats, MT01-brain-freeze).

Script quality gates — no render without all three:

• Hook: one sentence, the surprise or the unanswered question. Must land in ≤ 3 seconds of audio.
• Payoff: the hook's promise is fully honored before the end. No bait and switch.
• Fact-check table: every factual claim has a source. Complete this table before you touch ElevenLabs.

4B. Voice Generation

The channel's voice is permanently locked in brand.json → voice.voiceId. Always use this ID — never substitute a different voice for any episode.

Voice Audition Process (for a new channel)

1. Go to your voice provider's library (ElevenLabs, Play.ht, Murf, or similar)
2. Select 3 candidate voices that fit the voice register description from Stage 0
3. Generate 30 seconds of your actual script narration — not the demo text — with each voice
4. Listen on both speakers and earbuds. Pick the one that sounds right for the channel's world.
5. Record the voiceId in brand.json. Lock it. Do not revisit this decision.

Voice tool options

The key criteria for any voice tool: (1) stable API, (2) consistent voice reproduction across sessions, (3) per-character pricing that scales without shocking surprises. ElevenLabs scores best on #2 — critical for channel consistency.

4C. Image & Art Generation

Each scene in the episode needs one image. The image prompt = scene description + brand style suffix (from brand.json). The style suffix must be appended to every prompt — it's what keeps images looking like they belong to the same channel.

Image tool options

Animation options (for hook scenes)

Animated clips cost significantly more than stills ($1.50–$3+ per clip vs. $0.05 per image). Use animation selectively — the opening hook earns it. Default to stills for the explanation scenes.

4D. Music Generation

Music tool options

For clips longer than 47 seconds, crossfade-loop the generated audio:

ffmpeg -i music_47s.mp3 -filter_complex "[0][0]acrossfade=d=5[a];[a][0]acrossfade=d=5" music.mp3

4E. Build the Episode Queue Folder

xcopy /E /I "queue\_EPISODE-TEMPLATE" "queue\XX01"

The queue folder holds: captions.txt (one line per caption beat), config.py (scene-to-time mapping), voice.mp3, all scene images, and music.mp3.

config.py scene structure:

CONFIG = {
  "voice": "voice.mp3",
  "out": "XX01_topic.mp4",
  "wordmark_text": "Channel Name",
  "scenes": [
    {
      "image": "hook.png",
      "video": "hook.mp4",   # generated if animate:True
      "animate": True,       # True = AI video clip (costs more — use for hook only)
      "t": [0, None],
      "zoom": "slow",
      "prompt": "scene description ... [BRAND STYLE SUFFIX]"
    },
    {
      "image": "scene2.png",
      "t": [0, None],
      "zoom": "in",
      "prompt": "..."
    },
    {
      "image": "mascot.png",
      "t": [0, None],
      "zoom": "out",
      "prompt": "[MASCOT FULL DESCRIPTION], [POSE], [BRAND STYLE SUFFIX]"
    }
  ],
  "elements": []
}

4F. Pipeline Commands

# Full pipeline: voice + art + render
python produce.py XX01 --channel your-channel-slug

# Voice + art only (review before render)
python produce.py XX01 --channel your-channel-slug --no-render

# Render only (art and voice already generated)
python produce.py XX01 --channel your-channel-slug --skip-art --skip-voice

# Build caption timings (run AFTER voice is generated)
# groups = comma-separated caption counts per scene, must sum to total lines in captions.txt
python build_timing.py queue/XX01 3,4,3,4,5 --sub "your sign-off phrase" --signoff

Render output lands in review/XX01_topic.mp4. Do not move to UPLOAD READY without running the Stage 7 quality gate.

Localization generates translated captions, dubbed audio, and separate MP4s for each language — all from the same animation. The animation is made once; the language is swapped.

Default target languages: Spanish (es) · Portuguese (pt) · Hindi (hi) · German (de)

Choose languages based on the channel's audience. A cooking channel may prioritize Spanish and Portuguese. A tech channel may prioritize German and Japanese. Don't add a language just to have it — it costs API credits and time.

python ../../dub.py --render

Outputs per language: translated .txt, dubbed .mp3, .srt, and final .mp4. Play each localized render before marking it UPLOAD READY.

6A. Fill the Metadata Template

Copy 05_publishing/_metadata-template.md to 05_publishing/XX01-metadata.md. Fill for English and each language version.

6B. Publish via Blotato (Preferred Method)

1. 1
   Open Blotato → New Post

   Select the channel's YouTube, TikTok, and Instagram accounts (use the Blotato IDs from channels.json — not the account names).
2. 2
   Upload the English MP4

   From the channel's UPLOAD READY folder. Never upload from the review/ or queue/ folders.
3. 3
   Paste metadata

   Title, description, and hashtags from the filled metadata file. Check that the right language version is matched to each upload.
4. 4
   Schedule with platform-specific timing

   YouTube and Instagram: same day at the channel's publish_time. TikTok: typically 01:00 UTC the following day (audience timing differs). Record the schedule in channels.json.
5. 5
   Repeat for each language

   Same video file, swapped title/description/hashtags in the target language. Schedule on a rolling weekly cadence if producing multiple language versions.

6C. Automated Cross-Post (when R2 is configured)

# Publishes/schedules all live channels automatically
python network.py daily

# Check what's scheduled and what's running low
python network.py status
python network.py runway   # flags channels with < 14 days scheduled ahead

6D. Log the Upload

Add a row to 05_publishing/upload-log.md immediately after scheduling. This is how we track what's been posted and catch gaps in the schedule.

Quality

• Hook lands in the first 3 seconds
• The hook's promise is fully paid off before the end
• One idea, clearly and completely delivered — no tangents
• Looks and sounds like the same channel as the last video (brand consistent)
• Captions on, on-brand font and color, inside safe zones (not cut by UI chrome)
• Audio clean — no clipping, no dead air, loudness normalized, pacing feels right

Accuracy

• Every factual claim verified (fact-check table in the script is 100% complete)
• No overstated certainty — models are labeled as models, estimates as estimates
• YMYL topics (if applicable): "educational — not advice" framing confirmed throughout

Compliance

• Voice is synthetic reading original writing — no real-person imitation
• AI disclosure toggled on if any realistic footage of real people or real events is used
• All music and visuals are AI-generated or properly licensed — nothing copyrighted
• Under 5 uploads today on this channel; content has original value (not filler)

Metadata

• Title triggers curiosity AND includes the key topic word
• Description is 1–2 clear sentences — no keyword stuffing
• Tags include #shorts plus relevant topic hashtags
• First frame (thumbnail for Shorts) is visually strong — not a blur or mid-transition

Metrics we track

The 48-hour read

Log first-48h metrics in upload-log.md. Hook retention > 50% = the hook worked → use a similar open next time. If retention drops sharply at a specific beat → that beat needs to move faster. Top performer each week feeds the idea backlog.

Cadence phases

The repeating loop

Automation (n8n, network.py) only gets added when a manual step has been proven and repeated 3+ times. Never automate what you haven't fully validated by hand.

Per-video cost

Fixed monthly (shared across all channels)

Scale projection (stills-only, daily cadence)

— Add new lessons here with the channel name and date discovered. A lesson without a source is less useful. —

Step 0 — Install Claude Code

Claude Code is the AI coding environment used for every Vivere build. Install it first — you'll use it to run the bootstrap prompt and for all future development work.

npm install -g @anthropic-ai/claude-code
claude

npm install -g @anthropic-ai/claude-code
claude

Running claude opens a browser for Anthropic account authentication. Create a free account at anthropic.com if needed. Alternatively, download the Claude Code desktop app from claude.ai/code — same features, no terminal launch required.

Step 1 — Install System Prerequisites

The pipeline requires Python 3.11+, ffmpeg, git, and Node. Install all four before continuing.

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL \
https://raw.githubusercontent.com/Homebrew/\
install/HEAD/install.sh)"

# Install tools
brew install python@3.11
brew install ffmpeg
brew install git
brew install node

# Verify (open new terminal first)
python3 --version
ffmpeg -version
git --version
node --version

# Install via winget (comes with Windows 11)
winget install Python.Python.3.11
winget install Gyan.FFmpeg
winget install Git.Git
winget install OpenJS.NodeJS

# Open a NEW PowerShell window, then verify:
python --version
ffmpeg -version
git --version
node --version

Step 2 — Install VS Code & Extensions

Download from code.visualstudio.com (same installer works on both platforms). Then install these extensions (Cmd+Shift+X on Mac / Ctrl+Shift+X on Windows):

Step 3 — Project Setup

# Create project directory
mkdir -p ~/Developer/VivereChannels
cd ~/Developer/VivereChannels

# Get pipeline scripts from Joe (two options):
# A) Clone repo (if Joe gives you access):
git clone [REPO URL] .

# B) Unzip the scripts Joe sends you, then:
pip3 install -r requirements.txt

# Verify pipeline loads:
python3 produce.py --help

# Create project directory
New-Item -ItemType Directory -Force `
  -Path "C:\Users\$env:USERNAME\Desktop\Developer\VivereChannels"
Set-Location "C:\Users\$env:USERNAME\Desktop\Developer\VivereChannels"

# Get pipeline scripts from Joe (two options):
# A) Clone repo (if Joe gives you access):
git clone [REPO URL] .

# B) Unzip the scripts Joe sends, then:
pip install -r requirements.txt

# Verify pipeline loads:
python produce.py --help

Step 4 — Environment File (.env)

# Voice generation — create your own account at elevenlabs.io
ELEVENLABS_API_KEY=

# Image + video generation — create your own account at fal.ai (add $10 credit)
FAL_KEY=

# Cross-post CDN — get from Joe (shared Cloudflare R2 account)
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET_NAME=vivere-media
R2_PUBLIC_URL=

# Cross-post scheduling — get from Joe (shared Blotato account)
BLOTATO_API_KEY=

# YouTube auto-upload — set up per channel (see Stage 3 · Platform Accounts)
YOUTUBE_CLIENT_ID=
YOUTUBE_CLIENT_SECRET=

⚠ Never commit the .env file. It is in .gitignore — confirm with git status before any push. The file must exist at the project root (same level as channels.json).

Step 5 — Required External Accounts

Step 6 — Google Cloud / YouTube API Setup

One-time setup per ~3 channels. Skip this initially — complete when ready to automate uploads.

1. Go to console.cloud.google.com → Create new project (e.g. "Vivere Channels 1")
2. APIs & Services → Enable APIs → search "YouTube Data API v3" → Enable
3. Credentials → Create Credentials → OAuth 2.0 Client ID → Web application
4. Download the JSON → rename to client_secret.json → place in 06_pipeline/explainer-engine/
5. Add your YouTube channels as "Test users" under OAuth consent screen → Test users
6. First run of the pipeline with --upload flag will open a browser for authorization

Step 7 — Required VS Code Settings (recommended)

{
  "python.defaultInterpreterPath": "python3",
  "editor.formatOnSave": false,
  "files.exclude": { "**/__pycache__": true, "**/*.pyc": true },
  "editor.rulers": [100],
  "[markdown]": { "editor.wordWrap": "on" },
  "dotenv.enableAutocloaking": true
}

Note: On Windows, set "python.defaultInterpreterPath": "python" (without the 3). On macOS, python3 is correct.

Step 8 — Verify Full Setup

python3 --version        # 3.11+
ffmpeg -version          # any version
git --version            # any version
python3 -c "import PIL; print('Pillow OK')"
python3 -c "import dotenv; print('.env OK')"
python3 -c "import fal_client; print('fal OK')"
python3 -c "import elevenlabs; print('11labs OK')"
ls .env                  # should exist (not .env.example)

python --version         # 3.11+
ffmpeg -version          # any version
git --version            # any version
python -c "import PIL; print('Pillow OK')"
python -c "import dotenv; print('.env OK')"
python -c "import fal_client; print('fal OK')"
python -c "import elevenlabs; print('11labs OK')"
Test-Path .env           # should return True

Key Files

Pipeline Command Reference

# --- EPISODE PRODUCTION ---
# Full pipeline (voice + art + render)
python produce.py XX01 --channel your-slug

# Voice + art only (review assets before render)
python produce.py XX01 --channel your-slug --no-render

# Render only (skip generation — assets already exist)
python produce.py XX01 --channel your-slug --skip-art --skip-voice

# Force regenerate specific assets
python produce.py XX01 --channel your-slug --force-voice
python produce.py XX01 --channel your-slug --force-art

# Build caption timings (groups must sum to lines in captions.txt)
python build_timing.py queue/XX01 3,4,3,4,5 --sub "sign-off phrase" --signoff

# --- LOCALIZATION ---
# Run from inside queue/XX01/
python ../../dub.py --render

# --- NETWORK OPERATIONS ---
python network.py status      # all channels + scheduled runway
python network.py runway      # flags any channel under 14 days ahead
python network.py cost        # current cost model output
python network.py daily       # publish/schedule everything ready

# --- ADD A NEW CHANNEL ---
python network.py new-channel SLUG --name "Channel Name" --handle @handle \
  --niche "topic" --prefix XX --time 12:00 --category 27

Stage Summary