The Visualizer Content Pipeline

track:
  title: "JADED"
  artist: "moodmixformat"
  album: "MIXTAPE FORMAT"
  audio: "./audio/jaded.mp3"
  cover: "./assets/jaded-cover.jpg"

visualizer:
  theme: "tape-deck"
  color: "#f97316"

outputs:
  - platform: spotify-canvas
    width: 720
    height: 1280
    duration: 8
    loop: true
  - platform: instagram-reel
    width: 1080
    height: 1920
    duration: 15
  - platform: youtube-short
    width: 1080
    height: 1920
    duration: 60
  - platform: youtube-background
    width: 1920
    height: 1080
    duration: 0  # full track length

Build a Node.js CLI tool that batch-renders visualizer videos for multiple
platforms from a single audio file and release config. The tool uses Puppeteer
to headlessly capture a browser-based audio visualizer at different resolutions
and durations.

PROJECT STRUCTURE:
content-pipeline/
  package.json
  src/
    cli.js            (Commander-based CLI entry point)
    renderer.js       (Puppeteer headless rendering logic)
    config-loader.js  (Parse and validate release.yaml config)
    ffmpeg-wrapper.js (Optional format conversion WebM -> MP4)
    manifest.js       (Output manifest generator)
  templates/
    visualizer.html   (Self-contained audio visualizer page)
  release.yaml        (Sample release config)
  README.md

REQUIREMENTS:

1. CLI INTERFACE (src/cli.js)
   - Usage: node src/cli.js [options] <config-file>
   - Default config file: release.yaml in the current directory
   - --output or -o: output directory (default: ./output)
   - --preview: open the visualizer in a visible browser window instead of
     rendering headlessly (for testing/tweaking)
   - --draft: render at half resolution for faster preview renders
   - --format: output format, "webm" or "mp4" (default: "webm", mp4 requires
     ffmpeg)
   - --verbose or -v: print detailed progress including frame counts
   - Use Commander npm package for argument parsing

2. CONFIG LOADER (src/config-loader.js)
   - Parse YAML config file using js-yaml
   - Validate required fields: track.title, track.artist, track.audio,
     and at least one output entry
   - Each output entry requires: platform, width, height, duration
   - Resolve file paths relative to the config file location
   - If track.cover is specified, verify the file exists
   - If track.audio doesn't exist, exit with a clear error message
   - Return a normalized config object

3. VISUALIZER TEMPLATE (templates/visualizer.html)
   - A self-contained HTML page with an audio-reactive visualizer
   - Uses Web Audio API (AnalyserNode) to drive visual animation
   - Visual style: dark background (#09090b), audio waveform/frequency bars
     rendered on a canvas element
   - Accepts query parameters to customize:
     - audioSrc: path to audio file
     - coverArt: path to cover image (displayed centered behind the visualizer)
     - title: track title (rendered as text overlay, bottom area)
     - artist: artist name (rendered below title)
     - theme: visual theme name (default: "tape-deck")
     - color: accent color for visualizer elements (default: #f97316)
   - The "tape-deck" theme should include:
     - Subtle VHS/tape noise texture overlay (CSS-generated, not an image file)
     - Slightly rounded frequency bars with the accent color
     - Track title in a monospace font (Courier New or similar)
     - A thin horizontal line above the title area (like a tape deck's
       head position indicator)
   - The visualizer canvas must fill the entire viewport (no margins, no
     scrollbars) so Puppeteer captures it cleanly
   - Audio must autoplay when the page loads (Puppeteer allows this in
     headless mode)
   - Include a subtle fade-in on load (0.5s opacity transition)

4. RENDERER (src/renderer.js)
   - For each output in the config:
     a. Launch Puppeteer with a viewport matching the output dimensions
     b. Serve the visualizer.html locally (use a simple HTTP server like
        http-server or express, needed so audio files load correctly)
     c. Navigate to the visualizer page with query params for the current
        track's metadata
     d. Use Puppeteer's page.screencast() or page recording API to capture
        the viewport as video
     e. Record for the specified duration (or full audio length if duration
        is 0)
     f. Save the recording to the output directory
     g. Filename format: {platform}_{width}x{height}_{duration}s.webm
        (e.g., spotify-canvas_720x1280_8s.webm)
   - If --preview flag is set, launch with headless: false and don't record
     -- just open the visualizer in a visible browser for the user to watch
   - If --draft flag is set, halve the width and height for faster rendering
   - Print progress for each output: "Rendering spotify-canvas (720x1280,
     8s)... done"
   - Handle errors gracefully: if one output fails, log the error and
     continue with the next output

   IMPORTANT NOTE ON VIDEO CAPTURE:
   Puppeteer's screencast API may have limitations. As a robust fallback,
   use this approach:
   - Capture frames as PNG screenshots at 30fps using page.screenshot()
     in a loop with appropriate timing
   - After capturing all frames, use ffmpeg to encode them into a video
   - If ffmpeg is not available, save frames as individual PNGs in a
     subdirectory and log instructions for manual encoding
   - This frame-capture approach is more reliable across Puppeteer versions

5. FFMPEG WRAPPER (src/ffmpeg-wrapper.js)
   - Check if ffmpeg is available on the system (try running "ffmpeg -version")
   - If available:
     - Convert WebM to MP4 (H.264 + AAC) when --format mp4 is specified
     - Encode captured frames into video: ffmpeg -framerate 30 -i
       frame_%04d.png -i audio.mp3 -c:v libx264 -pix_fmt yuv420p
       -c:a aac output.mp4
     - Mux audio into the final video file
     - Delete intermediate frame files after successful encoding
   - If not available:
     - Log a warning: "ffmpeg not found. Output will be image frames only.
       Install ffmpeg for video output."
     - Keep frame PNGs as output
   - Export a function to check ffmpeg availability and a function to
     encode frames to video

6. MANIFEST GENERATOR (src/manifest.js)
   - After all outputs are rendered, generate a manifest.json in the output
     directory listing:
     {
       "track": { "title": "...", "artist": "...", "album": "..." },
       "generatedAt": "ISO timestamp",
       "outputs": [
         {
           "platform": "spotify-canvas",
           "file": "spotify-canvas_720x1280_8s.mp4",
           "width": 720,
           "height": 1280,
           "duration": 8,
           "fileSize": "1.2 MB",
           "format": "mp4"
         },
         ...
       ]
     }
   - Include file sizes (human-readable: KB or MB)
   - Print a summary table to the terminal after generation

7. SAMPLE RELEASE CONFIG (release.yaml)
   - Use the moodmixformat example:
     - Track: "JADED" from album "MIXTAPE FORMAT"
     - Audio path: ./audio/jaded.mp3 (user provides their own audio file)
     - Cover art: ./assets/jaded-cover.jpg (user provides their own)
     - Theme: tape-deck, color: #f97316
     - All four platform outputs as listed above

DEPENDENCIES: puppeteer, commander, js-yaml, express (for local file serving)

content-pipeline/
  package.json
  release.yaml
  README.md
  src/
    cli.js
    renderer.js
    config-loader.js
    ffmpeg-wrapper.js
    manifest.js
  templates/
    visualizer.html

Loading config: release.yaml
  Track: JADED by moodmixformat
  Cover: ./assets/jaded-cover.jpg
  Theme: tape-deck (#f97316)
  Outputs: 4 platforms

Starting local server on port 3456...

Rendering spotify-canvas (720x1280, 8s)... done [12s]
Rendering instagram-reel (1080x1920, 15s)... done [28s]
Rendering youtube-short (1080x1920, 60s)... done [94s]
Rendering youtube-background (1920x1080, full track)... done [187s]

Output directory: ./output/
  spotify-canvas_720x1280_8s.mp4      1.1 MB
  instagram-reel_1080x1920_15s.mp4    3.8 MB
  youtube-short_1080x1920_60s.mp4     12.4 MB
  youtube-background_1920x1080_238s.mp4  42.1 MB
  manifest.json                       0.4 KB

4 clips rendered, manifest written.

spotify-canvas_720x1280_8s.mp4        1.1 MB
instagram-reel_1080x1920_15s.mp4      3.8 MB
youtube-short_1080x1920_60s.mp4       12.4 MB
youtube-background_1920x1080_238s.mp4 42.1 MB
manifest.json                         0.4 KB

Add a --batch flag that accepts an album config YAML file instead of a single
release config. The album config has a tracks array, each with the same
structure as a single release config. When --batch is used, iterate through
every track and render all platform outputs for each one. Create a subdirectory
per track in the output directory (named after the track title, lowercased,
hyphens for spaces). Generate a master manifest.json at the album level that
lists all tracks and all outputs. Print a summary at the end: total tracks,
total clips rendered, total file size.

Add a --upload-youtube flag that uses the YouTube Data API v3 to upload
rendered clips directly. Require a credentials.json file (OAuth2 client
credentials from Google Cloud Console). On first run, open a browser for
OAuth consent and save the refresh token locally. Upload the youtube-short
output as a YouTube Short and the youtube-background output as a standard
video. Set the title to "{track.title} - {track.artist} [Visualizer]",
the description to "Visual: AI-generated tape deck visualizer", and add
tags from the release config. Print the YouTube URL after upload completes.

Add a --highlight flag that automatically picks the most energetic section
of the track for short-format outputs (Spotify Canvas, Instagram Reel).
Instead of using the first N seconds of audio, analyze the audio file to
find the peak energy section: read the audio as raw samples using an audio
decoding library, compute RMS energy in 1-second windows, find the window
with the highest energy, then expand outward to the required duration.
This way the Spotify Canvas gets the drop or climax of the track, not the
intro. Print which timestamp range was selected.

Add support for a "textOverlay" section in the release config that syncs
text to timestamps:

textOverlay:
  font: "Courier New"
  color: "#ffffff"
  entries:
    - text: "JADED"
      start: 0
      end: 3
      position: "center"
      size: 48
    - text: "out now on all platforms"
      start: 3
      end: 6
      position: "bottom"
      size: 24

Pass the overlay data to the visualizer template via query params or a
JSON endpoint. The visualizer should render the text with fade-in/fade-out
transitions (0.3s) at the specified timestamps. This is for promotional
clips where you want lyrics, release dates, or calls-to-action overlaid
on the visualizer.