Developer & Power User Guide

Command Line Interface

Automate lyric alignment and batch-sync entire libraries directly from your terminal or workflow scripts.

How It Works

LyricSynapse includes a built-in CLI interface with seamless single-instance orchestration. Whether the app is already open or closed, invoking the CLI from your terminal instantly triggers Batch Mode with automatic folder scanning.

  • App Closed (Cold Start): Opens LyricSynapse directly into Batch Mode, adds all audio files recursively, and starts alignment automatically.
  • App Running (Hot Queue): Activates and focuses the existing window, switches to Batch Mode, and appends the new tracks into the queue immediately.
  • Supported Audio Formats: .mp3, .m4a, .flac, .wav, .ogg, .aac, .opus, .wma.

Platform Setup

On macOS, the executable is located inside the application bundle at:

Binary Path 
/Applications/LyricSynapse.app/Contents/MacOS/lyric-synapse

Option A: Create a System Symlink (Recommended)

Link the binary into your PATH so you can run lyric-synapse anywhere:

Terminal (Bash / Zsh) 
sudo ln -sf /Applications/LyricSynapse.app/Contents/MacOS/lyric-synapse /usr/local/bin/lyric-synapse

Option B: Add a Shell Alias

Alternatively, add an alias to your ~/.zshrc or ~/.bashrc:

~/.zshrc 
alias lyric-synapse="/Applications/LyricSynapse.app/Contents/MacOS/lyric-synapse"

Command Syntax & Examples

Basic syntax for starting a batch alignment:

Syntax 
lyric-synapse --batch [OPTIONS] <PATHS...>

1. Align a Single Audio Track

Loads a track, locates its matching .txt lyric file (or existing metadata), and performs alignment:

Terminal 
lyric-synapse --batch "./Starfall Melody.mp3"

2. Batch Process an Entire Directory (Recursive)

Scans the folder and all sub-folders, queues every discovered audio file, and synchronizes them:

Terminal 
lyric-synapse --batch ~/Music/Album2026/

3. Custom Output: Enhanced Word-Level LRC & SYLT Tag

Configure specific output formats for this batch run via flags:

Terminal 
lyric-synapse --batch --enhanced-lrc --embed-sylt ~/Music/Album/

4. Load Files Without Auto-Running

If you prefer to review the file queue in the UI before starting AI alignment, use --no-auto-run:

Terminal 
lyric-synapse --batch --no-auto-run ~/Music/Album/

Options Reference

All batch configuration flags accept both positive and negative variants (e.g. --output-lrc or --no-output-lrc).

Flag Default Description
--batch <paths...> Required Starts Batch Mode and adds audio files or directories (recursive scan).
--no-auto-run Auto-run on Populates the batch queue without immediately executing the alignment process.
--output-lsy
--no-output-lsy		 Enabled Generates LyricSynapse timing project sidecar files (.lsy).
--output-lrc
--no-output-lrc		 Enabled Exports standard line-level synchronized lyrics (.lrc).
--enhanced-lrc
--no-enhanced-lrc		 Disabled Includes word-level karaoke timing tags <00:00.00> inside .lrc files.
--output-srt
--no-output-srt		 Disabled Exports SubRip subtitle format (.srt) alongside audio files.
--output-vtt
--no-output-vtt		 Disabled Exports WebVTT subtitle format (.vtt) alongside audio files.
--embed-uslt
--no-embed-uslt		 Disabled Embeds unsynchronized lyrics tag into audio file metadata (ID3v2.3 / MP4).
--embed-sylt
--no-embed-sylt		 Disabled Embeds synchronized word-level SYLT tags into audio file metadata.
--ignore-existing-lsy
--no-ignore-existing-lsy		 Disabled Forces AI alignment even if a pre-existing .lsy project sidecar exists.

Automated Scripting & Integration

LyricSynapse CLI can be seamlessly integrated into music production pipelines, AI generation scripts (e.g. ComfyUI, Suno, Udio, YuE), or folder-watch daemons:

Python Automation Example 
import subprocess

def auto_align_lyrics(music_folder: str):
    subprocess.run([
        "lyric-synapse",
        "--batch",
        "--enhanced-lrc",
        "--embed-uslt",
        music_folder
    ], check=True)