sync-captions-to-music

Generate beat-synced captions for music-video ads with burned-in subtitles.

6|1|Updated May 29, 2026
One-click install
npx skills add https://github.com/gooseworks-ai/gooseworks-ads-skills --skill sync-captions-to-music
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: sync-captions-to-music
Source: https://github.com/gooseworks-ai/gooseworks-ads-skills/tree/main/skills/atoms/captions/sync-captions-to-music
Command: npx skills add https://github.com/gooseworks-ai/gooseworks-ads-skills --skill sync-captions-to-music

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires ffmpeg, python, and includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill generates beat-synced captions for music-video ads, ensuring that captions match the rhythm and timing of the music.

Core Features & Use Cases

  • Beat-Synced Captions: Captions are synchronized with the music's rhythm and timing.
  • Timestamp Alignment: Uses word-level timestamps from music metadata or transcriptions.
  • Chunking and Placement: Lyric chunks are optimized for readability and timing, with customizable font and placement.
  • Use Case: Before a music-video ad goes live, use this Skill to add captions that enhance the viewer experience by matching the song's rhythm.

Quick Start

Run the sync-captions-to-music skill with the following command:

python3 scripts/sync.py \
  --video <path_to_video> \
  --lyrics <path_to_lyrics> \
  --timestamps <path_to_timestamps> \
  --output <path_to_output_video> \
  --accent-words "word1,word2" \
  --chunk-size 3 \
  --placement mid \
  --preview-strip <path_to_preview_strip>

Frequently Asked Questions about sync-captions-to-music

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create beat-synced captions for a music video?

To create beat-synced captions for a music video, this Skill aligns word-level timestamps from lyrics with the audio rhythm. It applies chunking and placement logic, then burns the subtitles directly into the video output using ffmpeg.

Do I need to provide word-level timestamps to generate music video subtitles?

You do not need to manually provide word-level timestamps to generate music video subtitles. While the Skill can process provided music metadata and transcription data, it uses Whisper as a fallback to automatically transcribe and timestamp your lyrics.

Can I use ffmpeg to burn subtitles with custom fonts and placement into music video ads?

Yes, you can use ffmpeg to burn subtitles with custom fonts and placement into music video ads. This Skill leverages ffmpeg alongside python libraries to apply customizable lyric chunking, accent words, and specific screen placement.

What is the best way to align lyrics with rhythm for video subtitles?

The best way to align lyrics with rhythm for video subtitles is by matching word-level transcription timestamps to the music's beat. This Skill optimizes lyric chunks for readability and timing to ensure captions match the song's rhythm perfectly.

Does python support automatic lyric chunking for timestamp alignment?

Yes, python supports automatic lyric chunking for timestamp alignment. This Skill uses python scripts to process your video and lyrics, applying configurable chunk sizes and placement logic to optimize subtitle readability before rendering.