LyricSync 🎵

A high-performance Rust tool for embedding LRC lyrics into audio files (FLAC, MP3, M4A). Perfect for organizing your music library with synchronized lyrics.

Features ✨

• Multi-format Support: FLAC, MP3, and M4A files
• Smart Processing: Skip files that already have embedded lyrics
• Batch Operations: Process entire directories recursively
• File Management: Optionally delete LRC files after embedding
• Progress Tracking: Real-time progress bar with detailed statistics
• Shell Completion: Full shell completion support for bash, zsh, fish, and more
• High Performance: Built in Rust for blazing fast processing

Installation 🔧

Pre-built Binaries

Download the latest release from the releases page.

From Source

git clone https://github.com/dantescur/lyricsync.git
cd lyricsync
cargo install --path .

Cargo Install

cargo install lyricsync

Usage 🚀

Basic Usage

# Embed lyrics for all audio files in a directory
lyricsync -d /path/to/music

# Skip files that already have lyrics and delete LRC files after embedding
lyricsync -d /path/to/music -s -r

# Process subdirectories recursively
lyricsync -d /path/to/music -R

Command Line Options

Shell Completion

Generate completion scripts for your shell:

# Bash
lyricsync --generate-completion bash > ~/.config/bash_completion/lyricsync

# Zsh
lyricsync --generate-completion zsh > ~/.zsh/completions/_lyricsync

# Fish
lyricsync --generate-completion fish > ~/.config/fish/completions/lyricsync.fish

# PowerShell
lyricsync --generate-completion powershell > lyricsync.ps1

File Structure Requirements 📁

Your music directory should be organized like this:

music_folder/
├── song1.flac
├── song1.lrc
├── song2.mp3
├── song2.lrc
├── song3.m4a
├── song3.lrc
├── album1/
│   ├── track1.flac
│   ├── track1.lrc
│   └── track2.flac
└── album2/
    ├── song1.m4a
    └── song1.lrc

Note: LRC files must have the same base name as their corresponding audio files.

Examples 💡

Organize Your Music Library

# Process your entire music library
lyricsync -d "~/Music" -s -r -R

Process Specific Albums

# Process a single album, keeping LRC files
lyricsync -d "~/Music/My_Favorite_Album"

# Process and clean up LRC files
lyricsync -d "~/Music/My_Favorite_Album" -r

Supported Formats 🔍

Performance 📊

LyricSync is built in Rust for maximum performance:

• Fast Processing: Processes thousands of files in seconds
• Low Memory Usage: Efficient streaming and metadata handling

Error Handling ⚠️

• Failed embeddings are clearly reported
• Original LRC files are preserved as .lrc.failed
• Detailed error messages for troubleshooting
• Progress tracking with file-specific status

Building from Source 🛠️

Prerequisites

• Rust 1.70+ (install via rustup)

Build Steps

# Debug build
cargo build

# Release build (recommended)
cargo build --release

# Check code quality
cargo clippy --all-targets --all-features --workspace -- -D warnings

Development Setup

# Install git hooks (runs tests, clippy, and formatting checks before push)
./scripts/setup-git-hooks.sh

# Run tests
cargo test

# Format code
cargo fmt

# Run clippy
cargo clippy --all-targets --all-features -- -D warnings

Versioning

The version is managed in Cargo.toml and automatically used throughout the codebase. The CLI version is derived from Cargo.toml at build time.

Bumping version:

# Bump patch version (0.1.0 -> 0.1.1)
./scripts/bump-version.sh patch

# Bump minor version (0.1.0 -> 0.2.0)
./scripts/bump-version.sh minor

# Bump major version (0.1.0 -> 1.0.0)
./scripts/bump-version.sh major

# Set specific version
./scripts/bump-version.sh 0.2.0

Release workflow:

1. Update version: ./scripts/bump-version.sh [major|minor|patch]
2. Commit: git commit -am "Bump version to X.Y.Z"
3. Tag: git tag -a vX.Y.Z -m "Release vX.Y.Z"
4. Push: git push && git push --tags

The CI workflow will automatically build and release binaries for all platforms when a tag is pushed.

Contributing 🤝

Contributions are welcome! Please feel free to submit pull requests, open issues , or suggest new features.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License 📄

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments 🙏

• Highly inspired by lrcput

Support 💬

If you encounter any issues or have questions:

1. Check the issues page
2. Create a new issue with detailed information
3. Include your operating system and LyricSync version

Made with ❤️ by dantescur

Sync your lyrics, enhance your music experience!