Contents
A lyric video puts the words of a song on screen while it plays. In the karaoke style, each word fills with color as it’s sung, so viewers can sing along without losing their place.
Music videos have a huge audience. YouTube’s head of music wrote in March 2026 about “billions of logged-in viewers watching music videos on our platform each month.” A lyric video is one of the simplest to make: it needs only the song, the words and a background.
This guide shows how to make a lyric video with Python and Shotstack’s video editing API. You give it a song and a synced lyrics file, and you get back an MP4 where every word lights up on time.
TL;DR
- A
rich-captionclip with"animation": {"style": "karaoke"}fills each word with a second color as it’s sung. - The words and their times come from a subtitle file. A timestamp before each word makes the fill follow the singing.
- The script below converts a synced lyrics file (LRC) to WebVTT with word timestamps. It uploads the file with the Ingest API and renders the video.
- The demo is a 20 second song with 6 lines and 54 timed words, rendered at 1280 x 720.
How a karaoke lyric video works
The Edit API renders a timeline that you describe in JSON. A lyric video has three tracks:
- The lyrics. A
rich-captionclip reads a subtitle file and shows each cue at its time. - The song. An audio clip with
"length": "auto", so the video is as long as the song. - A background. Any video or image. This one is a drive through a tunnel.
The karaoke animation does the rest. In the words of the rich captions guide: “All words are visible from the start; the active word changes to the active color.” font.color sets the color of the words still to come, and active.font.color sets the fill.
Line timing or word timing
The fill follows the times in your lyrics file, so how much timing you give it decides how it moves:
- One time per line. The fill sweeps across the line at an even pace, from the moment the line starts to the moment it ends.
- One time per word. The fill reaches each word when it’s sung. A word held for a long note fills slowly, and a fast run of words fills fast.
WebVTT, the caption format on the web, has a tag for word times inside a cue. MDN’s WebVTT format reference puts it plainly: “Timestamp tags are used to enable karaoke-style captions.” This is the last cue of the demo song:
00:00:13.080 --> 00:00:14.820
I <00:00:13.100>won't <00:00:13.240>fade <00:00:13.400>into <00:00:13.580>the <00:00:13.860>background <00:00:14.100>nowThe first word starts with the cue, so it needs no tag. Every word after it carries its own start time.
Start from a synced lyrics file
LRC is a plain text format for lyrics synced to a song. Each line starts with a time tag, written [mm:ss.xx] for minutes, seconds and hundredths of a second. The enhanced format on Wikipedia’s LRC page adds a <mm:ss.xx> tag before each word, so a player can highlight each word as it’s sung.
This is the LRC file for the demo song:
[00:00.00] <00:00.00> Wake <00:00.42> up <00:00.60> to <00:00.74> the <00:00.90> same <00:01.08> old <00:01.20> static <00:01.46> on <00:01.74> the <00:01.88> line <00:02.24>
[00:02.68] <00:02.68> Every <00:03.04> word <00:03.32> I <00:03.44> meant <00:03.60> got <00:03.74> lost <00:03.98> along <00:04.20> the <00:04.38> wire <00:04.70>
[00:05.38] <00:05.38> I <00:05.50> keep <00:05.64> running <00:05.90> back <00:06.12> the <00:06.28> tape <00:06.42> to <00:06.58> find <00:06.82> the <00:06.92> sign <00:07.26>
[00:07.94] <00:07.94> Now <00:08.02> the <00:08.18> silence <00:08.36> in <00:08.68> this <00:08.82> room <00:09.00> is <00:09.10> set <00:09.30> on <00:09.42> fire <00:09.70>
[00:10.46] <00:10.46> Turn <00:10.56> it <00:10.74> up <00:10.90> until <00:11.08> the <00:11.34> walls <00:11.58> come <00:11.84> down <00:12.34>
[00:13.08] <00:13.08> I <00:13.10> won't <00:13.24> fade <00:13.40> into <00:13.58> the <00:13.86> background <00:14.10> now <00:14.82>The tag after the last word marks when the line ends. Move it later to keep a line on screen for longer.
A plain LRC file with line times only works too. Each line then ends when the next one starts, and the fill moves at an even pace. End the file with an empty tag, such as [00:20.00], to give the last line its end. Lines without a time, and tags such as [ar:Artist], are skipped.
Make a lyric video with Python
The script reads lyrics.lrc, writes a WebVTT file with a timestamp before each word, uploads it, and renders the song over a background clip. The song and the tunnel clip are both hosted by Shotstack.
The script uses only the Python standard library. Set SHOTSTACK_API_KEY to the API key from your Shotstack dashboard, then run it with Python 3. Each render uses credits from your plan, as listed on the pricing page.
import itertools
import json
import os
import re
import sys
import time
import urllib.error
import urllib.request
EDIT = "https://api.shotstack.io/edit/v1"
INGEST = "https://api.shotstack.io/ingest/v1"
CDN = "https://d2jn8jtjz02j0j.cloudfront.net"
SONG = f"{CDN}/make_lyric_video_python_song_8d21183a2b.mp3"
BACKGROUND = "https://shotstack-assets.s3.amazonaws.com/footage/cars-tunnel.mp4"
FONT = "https://fonts.gstatic.com/s/oswald/v57/TK3iWkUHHAIjg75GHjUHte5fKg.ttf"
LYRICS = "lyrics.lrc"
LINE = re.compile(r"\[(\d+):(\d+(?:\.\d+)?)\](.*)")
WORD = re.compile(r"<(\d+):(\d+(?:\.\d+)?)>")
def call(url, body=None):
data = json.dumps(body).encode() if body is not None else None
headers = {
"x-api-key": os.environ["SHOTSTACK_API_KEY"],
"Content-Type": "application/json",
}
try:
request = urllib.request.Request(url, data, headers)
with urllib.request.urlopen(request) as response:
return json.load(response)
except urllib.error.HTTPError as error:
sys.exit(f"HTTP {error.code}: {' '.join(error.read().decode().split())[:300]}")
def to_seconds(minutes, seconds):
return int(minutes) * 60 + float(seconds)
def parse_lrc(text):
"""Return each sung line of an LRC file with its start, end and timed words."""
lines = []
for raw in text.splitlines():
match = LINE.match(raw.strip())
if not match:
continue
start = to_seconds(match[1], match[2])
parts = WORD.split(match[3])
words = [(start, parts[0].strip())] if parts[0].strip() else []
end = None
for minutes, seconds, word in zip(parts[1::3], parts[2::3], parts[3::3]):
if word.strip():
words.append((to_seconds(minutes, seconds), word.strip()))
else:
end = to_seconds(minutes, seconds)
lines.append({"start": start, "end": end, "words": words})
for line, after in itertools.pairwise(lines):
line["end"] = line["end"] or after["start"]
return [line for line in lines if line["words"] and line["end"]]
def vtt_time(seconds):
minutes, seconds = divmod(seconds, 60)
return f"00:{int(minutes):02d}:{seconds:06.3f}"
def to_vtt(lines):
"""Write one cue per line, with a timestamp before each word after the first."""
cues = ["WEBVTT", ""]
for line in lines:
words = [
word if at <= line["start"] else f"<{vtt_time(at)}>{word}"
for at, word in line["words"]
]
timing = f"{vtt_time(line['start'])} --> {vtt_time(line['end'])}"
cues += [timing, " ".join(words), ""]
return "\n".join(cues)
def upload(data, filename):
"""Host a file with the Ingest API and return its URL."""
source = call(f"{INGEST}/upload", {"filename": filename})["data"]
put = urllib.request.Request(source["attributes"]["url"], data, method="PUT")
urllib.request.urlopen(put).close()
while True:
time.sleep(3)
attributes = call(f"{INGEST}/sources/{source['id']}")["data"]["attributes"]
if attributes["status"] == "ready":
return attributes["source"]
if attributes["status"] == "failed":
sys.exit(f"Upload failed: {attributes.get('error')}")
def build_edit(song_url, background_url, lyrics_url):
lyrics = {
"asset": {
"type": "rich-caption",
"src": lyrics_url,
"font": {"family": "Oswald", "size": 56, "weight": 700, "color": "#ffffff"},
"style": {"textTransform": "uppercase"},
"stroke": {"width": 2, "color": "#000000"},
"active": {"font": {"color": "#ff3b3b"}},
"animation": {"style": "karaoke"},
},
"start": 0,
"length": "end",
"width": 1200,
"height": 200,
"fit": "none",
}
song = {"asset": {"type": "audio", "src": song_url}, "start": 0, "length": "auto"}
background = {
"asset": {"type": "video", "src": background_url, "speed": 0.65},
"start": 0,
"length": "end",
"filter": "darken",
}
return {
"timeline": {
"fonts": [{"src": FONT}],
"tracks": [{"clips": [lyrics]}, {"clips": [song]}, {"clips": [background]}],
},
"output": {"format": "mp4", "resolution": "hd"},
}
if __name__ == "__main__":
if not os.environ.get("SHOTSTACK_API_KEY"):
sys.exit("Set SHOTSTACK_API_KEY first.")
with open(LYRICS, encoding="utf-8") as file:
lines = parse_lrc(file.read())
timed = sum(len(line["words"]) for line in lines)
print(f"Lyrics: {len(lines)} lines, {timed} timed words")
lyrics_url = upload(to_vtt(lines).encode(), "lyrics.vtt")
print("Lyrics file:", lyrics_url)
edit = build_edit(SONG, BACKGROUND, lyrics_url)
render_id = call(f"{EDIT}/render", edit)["response"]["id"]
print("Render queued:", render_id)
while True:
time.sleep(5)
status = call(f"{EDIT}/render/{render_id}")["response"]
if status["status"] == "done":
break
if status["status"] == "failed":
sys.exit(f"Render failed: {status.get('error')}")
print(status["url"])Save the LRC file above as lyrics.lrc in the same folder and run python lyric_video.py. It prints the number of lines and words, the URL of the uploaded lyrics file, the render ID and the URL of the video:
Lyrics: 6 lines, 54 timed words
Lyrics file: https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/35tqpmb0ya/zzz01m7n-f6d01-4b9tz-4wsnx-jzh9dq/source.vtt
Render queued: 2b3245bf-3102-4a3a-b663-ceb63886de03
https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/35tqpmb0ya/2b3245bf-3102-4a3a-b663-ceb63886de03.mp4This is the video from that run:
How the script works
parse_lrc()reads every line that starts with a time tag. It keeps each word with its start time, and the line’s end: the tag after the last word, or else the start of the next line.to_vtt()writes one WebVTT cue per line, with a timestamp before every word after the first.upload()hosts the VTT file with the Ingest API. It asks for an upload URL, sends the file, and waits until the file is ready. The.vttinfilenametells Ingest what kind of file it is.build_edit()puts the lyrics on the top track, the song below them and the background at the bottom.- The main block posts the edit and checks the render every five seconds until it’s done.
The tunnel clip is 13 seconds long and the song runs for 20. "speed": 0.65 plays the clip slower, so it lasts 20 seconds and covers the whole song. Our guide on how to speed up or slow down a video covers the speed setting.
With your own background, use a clip at least as long as the song, or an image.
Style the lyrics
- Colors.
font.coloris the color of the words still to come andactive.font.coloris the fill. White words with a red fill read well on dark footage. - Font. Add the URL of any Google Font file to
timeline.fontsand name the font infont.family. The demo uses Oswald in uppercase. - Size. The lyrics box is 1200 pixels wide on a 1280 pixel video, so each line at 56 pixels fits on one row. Make
sizesmaller if your lines are longer. - Animation.
karaokeis one of eight styles.highlightswitches each word to the active color at once, andtypewriterreveals the words one by one and keeps them on screen. - Vertical video. Add
"aspectRatio": "9:16"to theoutput, and make the lyrics box narrower. Our guide on how to generate YouTube Shorts with an API covers the vertical format.
Make your lyric video with Shotstack
You now have a script that turns a song and its synced lyrics into a karaoke-style lyric video. Put your own URLs in SONG and BACKGROUND, save your lyrics as lyrics.lrc, and run it again.
Create a free Shotstack account to get your API key and render your first lyric video.
Frequently asked questions (FAQs)
Can Shotstack time the lyrics for me?
Yes. Set "alias": "song" on the audio clip and "src": "alias://song" on the rich-caption clip. Shotstack then transcribes the song and times every word itself. The words on screen are the words it hears, so read them before you publish. A lyrics file puts your exact words on screen.
Can I use an SRT file instead?
Yes. A rich-caption clip reads SRT and VTT files. SRT has no tag for word times, so with SRT the fill sweeps across each cue at an even pace. Convert to VTT when you want the fill to follow every word. To make caption files from speech, see our guide to open and closed captions.
Why does my upload fail with “The file type could not be detected”?
Ingest needs to know what kind of file you send. Put the file name with its extension in the upload request, as the script does with "filename": "lyrics.vtt", or set a Content-Type header when you upload the file.
Can Shotstack make the song too?
Yes. The demo song was made with ElevenLabs Music through Shotstack, with a composition plan that sets the style and the lyrics of each section. The AI music generation guide shows how. Describe the style you want rather than an artist: naming a musician or band fails the generation.
How do I make lyric videos for a whole album?
Keep one LRC file per song, then call upload() and build_edit() for each one. Post every edit before you wait for the results. Our guide on how to bulk create videos from a CSV shows the same loop with a spreadsheet.