CTCLRC

CTCLRC is a Windows & Linux desktop application that produces synced LRC lyric files for your local music library, in three ways that combine into one pipeline:

• Download existing synced lyrics from online sources
• Generate timings with CTC Forced Alignment from plain lyrics
• Verify / edit timings in the Lyric Viewer, then optionally publish to LRCLIB

The lyrics text is treated as the ground truth, and the application estimates timestamps for each lyric line.

Android users should use CTCLRC-droid.

For standalone lyrics downloader, use LRCdownloader.

---

Usage

Use the packaged Windows application:

0. Build the executable according to your setup. (Hardware, OS)
1. Launch the application.
2. Add tracks: Add Audio…, Add Directory (recursive optional), or drag & drop files/folders.
3. Check settings / params according to your preferences. (languages, download sources, etc.)
4. Hit Generate to initiate autoamtic workflow. By default, Download from online sources runs first, tehn reamining plain lyrics will be ran through CTC model for alignment.
5. Once generated, use the Lyric Viewer / Editor button to check if the timings are correct. If not, you can edit the timing manually by editing timestamps (doube click) or use Tap-sync mode to re-tap timings line by line while the song plays.
6. Once done, you can save edited lyrics, embed them into the audio file, and optionally publish them on LRCLIB to help others.

• The generated .lrc file is saved in the same folder as the audio file (or the chosen output directory).

---

System Requirements

Minimum Requirements

Component	Minimum
OS	Windows 10 (64-bit)
CPU	Intel Core i5-8600 / AMD Ryzen 5 2600
Memory	8 GB RAM
Storage	5 GB available SSD space
GPU	Not required (CPU mode)

Recommended Requirements

Component	Recommended
OS	Windows 10/11 (64-bit)
CPU	Intel Core i5-12400 / AMD Ryzen 5 5600 or better
Memory	16+ GB RAM
Storage	NVMe SSD / Is there such thing as too much storage?
GPU	Nvidia or AMD GPU with Torch / 6GB+ VRAM

Notes

• CPU-only inference is fully supported, though slower than GPU inference.
• On CPU, alignment threads auto-scale to your host CPU (one core is left for the UI/OS, capped at 8). A CPU threads spinner in the options row lets you adjust it live; it is ignored on GPU. Override the default with the CTCLRC_CPU_THREADS environment variable (set before launching).
• Emissions batching defaults to 4 windows per forward pass; override with CTCLRC_BATCH_SIZE.
• In GPU mode, the generation will be significantly faster. For GPU mode to work, you need to install appropriate Torch versions. (CUDA/ROCm)
• Lyrics downloads reuse a single HTTP connection per provider instance (keep-alive) instead of opening a fresh TCP/TLS handshake per track.
• batch_utils.scan_directory walks the folder tree once instead of once per extension.
• The first launch downloads the alignment model (approximately 1–2 GB depending on the model format) unless it is bundled with the application.
• Longer audio files require proportionally more processing time.
• More complex tracks (especially autotunes, vocal chops) may benefit from separation with somehting like UVR then using vocal only for the processing.

---

Building on Windows

Install Dependencies

Run the following command from the project root directory:

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

For Nvidia GPU users + AMD GPU users on Linux

• Select appropriate options at Pytorch Website to get correct installation commands.

• Install Pytorch in the venv (run .venv\scripts\activate to enter venv)

  Once installed and confirmed torch and CUDA device is visible, you can manually build your executable.

For AMD GPU users on Windows

• For AMD ROCm + Pytorch support, refer to official instructions from AMD, since Torch on ROCm is not officially distributed at Pytorch.org.

• Install ROCm + Pytorch in the venv (run .venv\scripts\activate to enter venv)

  ROCm Docs - Install PyTorch for ROCm ROCm Docs - PyTorch via PIP installation

  Once installed and confirmed torch and CUDA device is visible, you can manually build your executable.

---

If you have a local copy of the ctc-forced-aligner ZIP package:

.\.venv\Scripts\python.exe -m pip install path\to\ctc-forced-aligner-main.zip

Build

.\.venv\Scripts\python.exe -m PyInstaller --clean --noconfirm CTCLRC.spec

• It may take 15+ minutes if you include torch, just go make a coffee or tea or what have you.

Output:

dist\CTCLRC\CTCLRC.exe

Important Distribution Notes

Builds use the directory (One-Dir) PyInstaller specification:

.\.venv\Scripts\python.exe -m PyInstaller --clean --noconfirm CTCLRC.spec

Output:

dist\CTCLRC\CTCLRC.exe

The output is a folder: CTCLRC.exe plus its support files. we use directory build instad of onefile so the launch doesn't take forever.

Move the whole dist\CTCLRC folder together and run CTCLRC.exe to launch it, give it a few seconds and you should see the splash screen.

---

Alignment Model

The application uses the following components:

• ctc-forced-aligner
• MahmoudAshraf/mms-300m-1130-forced-aligner

If the model is not bundled, the application automatically downloads it from Hugging Face during the first run and reuses the local cache afterward.

To create a fully offline executable, place the downloaded model in the following location before building:

models/mms-300m-1130-forced-aligner/

If the models/ directory exists, CTCLRC.spec automatically bundles it into the application.

The application also checks for the following directory next to the executable at runtime:

models/mms-300m-1130-forced-aligner/

---

Optional Offline Model Download

huggingface-cli download MahmoudAshraf/mms-300m-1130-forced-aligner --local-dir models\mms-300m-1130-forced-aligner

---

Running tests

.\.venv\Scripts\python.exe test_cleaning.py
.\.venv\Scripts\python.exe test_downloader_merge.py
.\.venv\Scripts\python.exe test_features.py   # includes a heavy alignment test; needs the model

---

Source Distribution

When distributing the source code, do not include the following:

• .venv
• build
• dist
• Generated .lrc files
• Model files
• Copyrighted audio files

Run:

.\make_source_zip.ps1

This creates:

CTCLRC-source.zip

---

Sources & credits

• LRCLIB: https://lrclib.net/docs
• Syncedlyrics (NetEase, Musixmatch, Megalobiz, Lrclib, Genius): https://github.com/moehmeni/syncedlyrics
• Spotify Lyrics API (opt-in, self-hosted instance + SP_DC cookie. may violate Spotify TOS, use at own risk): https://github.com/akashrchandran/spotify-lyrics-api
• SongSync (Inspiration for LRCdownloader): https://github.com/Lambada10/SongSync