Populating Songs

This page explains the basic workflow for generating karaoke lyrics in your .ass file using the populate_songs.py script and data from a Google Sheets database.

Triggering Song Population

To tell the script which song to generate and where to start, you need to add a specific Comment line in your Aegisub file:

1. Create a Comment Line: Add a new line in Aegisub.
2. Mark as Comment: Ensure the "Comment" checkbox is ticked for this line.
3. Set Style: Change the Style of the comment line to Song.
4. Set Start Time: Set the Start time of this comment line to the exact timestamp corresponding to the beginning of the very first timed syllable of the song. The End time is usually set to the same value.
5. Set Text: In the Text field, enter the exact title of the song as it appears in your Google Sheet database.

Example:

The following line will trigger generation for the song Mitaiken HORIZON, using 0:03:19.27 as the start time reference:

Comment: 0,0:03:19.27,0:03:19.27,Song,,0,0,0,,Mitaiken HORIZON

Running the Script

Execute the populate_songs.py script from your terminal, providing the path(s) to the .ass file(s) you want to process:

# Process a single file
python populate_songs.py input.ass

# Process multiple files
python populate_songs.py input1.ass input2.ass input3.ass ...

Generated Output

Running the script on an .ass file containing the example Song comment line above will typically generate the following components within the file:

1. Title Card:

   • An .ass event displaying the song's title (Romaji and English, if available) and credits (composer, arranger, writer from the database).
   • Styled with \an7 (top-left alignment).
   • Includes a 200ms fade-in and fade-out effect ({\fad(200,200)}).
   • Timing is based on the Song comment's start time (can be adjusted with the Offset modifier - see Modifiers).

2. Romaji Lyric Lines:

   • A series of .ass dialogue events, one for each line of the song's Romaji lyrics.
   • Each line is karaoke-timed (ktimed) syllable by syllable based on the database timings.
   • Default effect: A simple \kf fill, fading in and out from left to right.
   • Default positioning: Centered horizontally (960). Vertical position is 960 (lower-middle) by default. It is 65 if the line is marked as Secondary via modifier or database flag.
   • Actor coloring: The fill color changes from left to right based on actor changes specified in the database.
   • Identical Lyrics Handling: If the Romaji and English text for a specific line are the same in the database, the Romaji line is centered vertically at 1010 (slightly lower), or 65 if it is marked as Secondary.

3. English Translation Lines:

   • A series of .ass dialogue events for the English translation.
   • Default effect: Fades in and out from left to right (line-level, not ktimed by default).
   • Default positioning: Centered horizontally (960). Vertical position is 1015 (lower) by default, or 120 (upper) if the line is marked as Secondary (e.g., via modifier or database flag).
   • Actor coloring: The line color changes based on actor changes.
   • Identical Lyrics Handling: If the Romaji and English text for a specific line are the same in the database, the English line will still be generated but marked as a Comment. This prevents it from rendering in players, showing only the Romaji line in these cases.