Hardening LyricVid: From AI Lyric Renderer to a Secure CI/CD Video Platform

LyricVid began with a focused idea: take a song, synchronize its lyrics with the actual recording, and generate an animated video automatically.

By version 0.9.x, LyricVid had evolved into a terminal-driven media-production platform combining Python, faster-whisper, FFmpeg, Remotion, Docker, GitHub Actions, OAuth 2.0, and the YouTube Data API.

The project also gained a mature engineering lifecycle: CI/CD, CodeQL, Bandit, Trivy, Dependabot, dependency review, secret scanning, push protection, a repository-specific credential guard, branch protection, GHCR publishing, SBOM generation, provenance attestations, integration rendering, D2 documentation, and a detailed wiki.

Core media pipeline

Audio
  |
  v
ffprobe / Mutagen
  |
  +--> authored lyrics
  |
  +--> Whisper timing
           |
           v
     sequence alignment
           |
           v
      timed lyrics
           |
           v
       Remotion
           |
           v
        FFmpeg
           |
           v
          MP4

LyricVid deliberately separates what the lyrics say from when they are heard. Authored lyrics can remain the source of truth while faster-whisper provides acoustic timing. This preserves spelling, punctuation, capitalization, and section markers such as [Verse 1], [Chorus], [Bridge], and [Outro].

Fixing lyric timing artifacts

One subtle issue appeared when inferred timing spans caused some lines to flash briefly before they were actually sung. LyricVid was hardened to use conservative, non-overlapping display windows and to suppress extremely short inferred-only spans.

Remotion composition

Remotion provides the visual layer, with presets including cyberpunk, terminal-green, daemon-red, root-violet, system-amber, network-teal, neon-pink, minimal-clean, podcast, explainer, and metro-cinematic.

The renderer supports album artwork, logos, intros, outros, motion backgrounds, narration, landscape output, vertical Shorts/Reels output, and square output.

Detached rendering

Long Whisper and Remotion jobs can run detached from the terminal:

lyricvid . --style metro-cinematic --detach

Jobs can be inspected with:

lyricvid jobs

This makes the renderer suitable for persistent hosts such as a home Linux server or remote workstation.

YouTube publishing

LyricVid integrates with YouTube Data API v3 through OAuth 2.0. Upload metadata can be kept in normal files instead of long shell arguments:

lyricvid upload video.mp4 \
  --title "Example" \
  --description-file description.md \
  --public

OAuth credentials and refresh tokens stay outside Git.

CI/CD

The GitHub repository now uses independent workflows for validation, CodeQL, supply-chain security, container publishing, integration rendering, releases, and dependency automation.

The Python matrix covers 3.10 through 3.13. A separate integration render smoke test exercises a real rendering path and validates the output with ffprobe.

Security checks

Bandit performs Python static analysis. CodeQL provides data-flow-oriented analysis. Trivy covers filesystem, dependency, container, secret, and misconfiguration surfaces. Dependency Review evaluates new dependencies before merge. Dependabot proposes updates across Python, npm, Docker, and GitHub Actions.

GitHub secret scanning and push protection are enabled, along with Dependabot security updates.

LyricVid also includes a custom credential guard for project-specific sensitive patterns such as .secrets/, youtube-oauth.json, youtube-token.json, client_secret_*.json, refresh tokens, private keys, cloud credentials, GitHub tokens, and credential-bearing database URLs.

Branch protection

The protected main branch requires important checks to pass, disallows force pushes and deletion, requires linear history, and requires conversation resolution.

That makes main a trust boundary rather than simply another branch.

Containers, GHCR, SBOMs, and provenance

Tagged releases can publish container images to GitHub Container Registry. Release automation also produces package artifacts, software bills of materials, and provenance/attestation data.

This helps answer not only “does the program work?” but also “what is in this artifact?” and “how was it produced?”

D2 and the illustrated wiki

The repository maintains architecture documentation as D2 source. More than twenty wiki diagrams cover alignment, rendering, CI/CD, security, YouTube publishing, background jobs, troubleshooting, and release workflows.

Remote icon dependencies were replaced with vendored local SVG assets to make the documentation reproducible and offline-safe. SVG outputs can also be converted to PNG for systems that render PNG more consistently.

From script to engineering system

The biggest change was moving from:

this script can render a video

to:

this repository has a defined engineering lifecycle

That lifecycle now includes design, implementation, testing, integration validation, security scanning, dependency management, secret protection, branch governance, containers, release automation, provenance, documentation, and operational workflows.

LyricVid is no longer only a lyric-video generator. It has become a reproducible, testable, documented, containerized, security-scanned media-production pipeline.