Lyric Manager

💬🎵 Lyric Manager is an open source, music lyric manager to align lyrics to your song collection!

---

✨ Features

• Two interface flavors
  • Graphical-User Interface
  • Command-Line Interface
• Fetches lyrics from three sources
  • Local text file
  • Pypi lyricsgenius genius db
  • Pypi lyric_extractor using GCS
• Supports one aligner
  • NUSLyrixAutoAlign
• Generates .json file containing lyric structure and timing data useful for rendering lyric visuals via other tools such as PlanMixPlay

Introduction

Lyric Manager's fetches lyrics and aligns them to music. Finally, it generates a .json file containing lyric structure and timing data. Lyric Manager is primarily a 'glue tool' and relies heavily on external resources for both the fetching and aligning on lyrics. In other words, the tool is most functional in conjunction with other tools, some of which require a bit of setup. For more details, read the setup section.

Who is Lyric Manager for?

Given that Lyric Manager is a 'glue tool' and requires additional external tools to fully work, it's likely most useful for:

• Developers who want to work with audio and lyrics
• People who are keen to generate data for external tools (like PlanMixPlay) to create lyric-based visuals, see video below.

Requirements

• Operating System
  • Windows 8 or newer - GUI or CLI - Lyric fetching only - Alignment files must be generated in Linux.
  • Ubuntu 20.04 or newer - GUI or CLI
  • Ubuntu 18.04 - CLI only (GUI uses Qt6 which doesn't work out-of-the-box on this ubuntu version or older)

If running Lyric Manager directly via a Python interpreter, you'll likely need at least 3.8. It's only actively tested with 3.11 though.

Setup and usage

Full use of Lyric Manager consists of three steps:

1. Download either a binary release or Python source to run.
2. Setup remote lyric fetchers or provide local lyric text files.
3. Setup lyric aligner

LyricManager

Binary

Download a binary release via Github. Windows GUI only, with Ubuntu binaries coming soon.

Mac OS I'd support if I had access to Apple hardware :(

Source

• Install Python 3.7 or newer.
• Check-out the LyricManager repository.
• Compile a resources.py from the lyric_manager.qrc file.
• Install Python package requirements via requirements.txt, then run GUI / CLI version as needed.

If using the CLI version use the provided settings-example.yaml file to set the appropriate settings, and execute lyric_manager_cli.py.

LyricFetcher sources

Lyric Manager supports the following sources:

• Local .txt file with the same name as the audio file, e.g. Artist - Song Name.txt would accompany Artist - Song Name.mp3. Place this file next to your audio or in Lyric Manager's working directory.
• Genius lyrics database. An API key will be required, visit that Genius docs for a link to generating a client access token.
• Google Custom Search API. You'll need an API Key and Engine ID of Google Custom Search JSON API which you setup. The requirements section for the Pypi package lyrics-extractor explains how to set this up.

LyricAligners

Lyric Manager currently only supports one aligner:

• NUSAutoLyrixAlign which runs via Singularity on Linux.
  • I can confirm it works on Ubuntu 22.04 after some minor patching work.

Input / Output

Lyric Manager uses the following input/output files, for a given Artist - Song.mp3:

Input / Output	Filename	Format	Description
Input	Artist - Song.mp3	Audio	Audio file for which to fetch and align lyrics.
Input	Artist - Song.txt	Text	Local text file containing lyrics for Artist - Song.mp3. Required, if you opt to use LocalFile as one of the lyric fetchers.
Input & Output	Artist - Song.{fetcher}_source, e.g. Artist - Song.genius_source	Json	Generated by LyricManager for any of the lyric fetchers using remote sources.
Input & Output	Artist - Song.{fetcher}_sanitized_text, e.g. Artist - Song.genius_sanitized_text	Text	Generated by LyricManager from the above source file.
Input & Output	Artist - Song.alignment_ready	Text	Generated by LyricManager, formatted to be used as input for NUSAutoLyrixAlign.
Input & Output	Artist - Song.nusalaoffline	Text	Generated by LyricManager via NUSAutoLyrixAlign.
Output	Artist - Song.aligned_lyrics	Json	Contains structured lyrics and timing information as detailed below.

Files denoted as 'Input & Output' are intermediate data, saved to disk in order to allow for quicker future execution by not having to re-download and re-calculate outcomes.

Example contents of Artist - Song.aligned_lyrics:

{
    // Commentary inserted for clarity (not present in actual output!)
    "schema_version": "2.0.0", // A schema version to better track improvements / breakage
    "lyric_lines": [
        // lyric_lines typically contains multiple entries, one per line in the original lyric text.
        // Lyric Manager retains the lyric format structure (i.e. which words are in which lines)
        // from the original lyrics.
        // This example includes just a single entry.
        {
            "text": "Oxy-toxins flowing,", // One single line of lyrics
            "time_start": 107.82,         // Start time of full lyric line in seconds (from beginning of .mp3 file)
            "time_end": 110.43,           // End time of full lyric line in seconds (from beginning of .mp3 file)
            "lyric_words": [
                {
                    "original": "Oxy",              // Original text of single lyric word
                    "single": "Oxy",                // Modified text, expected to be more presentable as single word (see example below)
                    "word_split_char_pre": "",      // Character (if present) which is part of pre-split
                    "word_split_char_post": "-",    // Character (if present) which is part of post-split
                    "time_start": 107.82,           // Start time of word in seconds (from beginning of .mp3 file)
                    "time_end": 108.57              // End time of word in seconds (from beginning of .mp3 file)
                },
                {
                    "original": "toxins",
                    "single": "toxins",
                    "word_split_char_pre": "-",
                    "word_split_char_post": " ",
                    "time_start": 108.57,
                    "time_end": 109.8
                },
                {
                    "original": "flowing,",         // Original text of single lyric word - note the presence of the "," character
                    "single": "flowing",            // More presentable 'single word version' without the "," character
                    "word_split_char_pre": " ",
                    "word_split_char_post": "",
                    "time_start": 109.8,
                    "time_end": 110.43
                }
            ]
        }
	]
}

Project Files Layout

lyric-manager/
│
├── data/
│   ├── fetch_history.genius    - Record of time-out's or bad requests.
│   ├── lyric_manager.log       - Log output, generated at run-time.
│   ├── settings-example.yaml   - Settings example to copy and rename to settings.yaml
│   └── settings.yaml           - Your specific settings to run Lyric Manager.
│
├── docs/
│   ├── images/
│
├── Reports/			- Generated folder containing reports of fetching and aligning by LyricManager.
│   ├── 2022-07-10_15:14:01 Alignment Report.txt    - Results of alignment process executed at this date/time
│   │   ├── ...
│   └── 2022-07-10_15:14:01 Alignment Report.txt    - Results of alignment process executed at this date/time
│
├── resources/			- Resource files used by LyricManager such as Qt .ui file and icon .ico file.
│
├── src/
│   └── lyric-manager		- LyricManager source.
│
├── WorkingDirectory/		- Generated folder containing LyricManager generated files while fetching and aligning.
│
├── freeze*		    - File(s) related to "freezing binaries" of LyricManager.
├── lyric_manager_cli.py    - LyricManager Command-Line interface version.
├── lyric_manager_gui.py    - LyricManager Graphical-user interface version.
├── fetch_history.genius    - Record of time-out's or bad requests.
├── lyric_manager.log       - Log output, generated at run-time.
├── settings-example.yaml   - Settings example to copy and rename to settings.yaml
└── settings.yaml           - Your specific settings to run Lyric Manager.

Limitations

Lyric Manager has a number of known limitations:

• If the 'artist_song_name_source' is set to 'FileName', LyricManager expects the following filename convention: " - .audio_extension", This cannot currently be re-configured.
• LyricManager (currently) only supports a single lyric aligner, i.e. NUSAutoLyrixAlign offline (found here: https://github.com/chitralekha18/AutoLyrixAlign)
  • In the meantime, you can use the online version of NUSAutoLyrixAlign (found here: https://autolyrixalign.hltnus.org/) and rename the output (for Audacity - selected in their online tool) to be the offline extension, e.g. song.nusalaoffline

External Resources and Libarries

FontAwesome Fonts: Copyright (C) 2023 Fonticons, Inc. Licensed under a Creative Commons Attribution 4.0 International License. See CC-BY-4.0.txt file for details. Website: https://fontawesome.com/ Note: Despite the fact that the .svg files refer to the Pro license. These fonts are not Pro fonts. This is a confirmed bug in the svg files provided via the free-version that FontAwesome are working to fix.

Qt: Copyright (C) 2018 The Qt Company Ltd. Licensed under GPL license, see LICENSE file for details. Website: https://www.qt.io/

FAQ

I'm getting the error "version `GLIBC_2.28' not found"!

This will occur on Ubuntu 18.04, as Qt6 requires Ubuntu 20.04.