Tunz#

Tunz is a command-line tool designed to synchronize a music library to various destinations, including local folders and iPods. It manages a local database of your music, allowing for organized syncing, transcoding, and filtering.

Features#

• Library Management: Scans and indexes music files from specified source directories into a local SQLite database.
• Synchronization: Syncs your indexed music library to a destination folder or device.
• iPod Support: Supports syncing directly to iPods (requires libgpod), including database updates and automatic transcoding.
• Transcoding: Automatically converts lossless files to lossy formats (AAC, MP3, OGG, Opus) during sync to save space or ensure compatibility. Uses FFMpeg for conversion.
• Filtering: Allows writing custom scripts (using Rhai) to filter which tracks are synced based on metadata.
• Duplicate Detection: Identifies albums that are stored in more than one audio format.
• Smart Updates: Tracks changes in your source directories and updates the library accordingly.

Installation#

Tunz is written in Rust and requires a few system dependencies to build and run.

Prerequisites#

Ensure you have the following installed on your system:

• Rust: The Rust toolchain (cargo, rustc).
• FFmpeg: Required at runtime for audio transcoding, minimum version 8 with libfdk-aac support (see here for a build script that includes libfdk-aac).
• libgpod: Required for iPod support (libgpod-dev or equivalent package).
• Clang: Required for generating bindings to libgpod.
• pkg-config: Required for the build process to locate libraries.

Building from Source#

Clone the repository and build the project using Cargo:

cargo build --release

The compiled binary will be located in target/release/tunz. You can move this to a directory in your PATH for easier access.

Usage#

1. Adding Music to the Library#

First, you need to populate the Tunz database with your music files.

tunz add --source /path/to/your/music

You can specify multiple sources by repeating the --source flag.

To update the database later (e.g., if you added new files to the source directory):

tunz update

2. Synchronizing Music#

To sync your library to a destination folder:

tunz sync --destination /path/to/destination

Options:

• --dry-run: Preview what files will be copied or deleted without making changes.
• --no-delete: Prevent Tunz from deleting files in the destination that are not in the source library.
• --threads: Specify the number of threads to use for copying and transcoding (defaults to the number of available CPUs).

3. Syncing to an iPod#

To sync to a mounted iPod:

tunz sync --destination /mnt/ipod --ipod

This will automatically transcode files to a format compatible with the iPod (AAC VBR quality 5).

If this is a new iPod, you may need to initialize it first (requires root privileges to read metadata from the iPod ROM partition):

sudo tunz settings initialize-ipod --path /mnt/ipod --model <MODEL_NUMBER>

4. Transcoding Settings#

You can configure Tunz to transcode files when syncing to a standard folder (non-iPod).

tunz settings transcode --destination /path/to/destination --enabled true --codec mp3 --bitrate cbr:320k

Supported codecs: aac, mp3, ogg, opus.

Supported bitrates:

• Constant Bitrate (CBR): Use format cbr:<bitrate>k (e.g., cbr:320k, cbr:128k).
• Variable Bitrate (VBR): Use format vbr:<quality> (e.g., vbr:5, vbr:2). This corresponds to the FFmpeg -q:a quality level (range depends on the codec, e.g., 1-5 for AAC, 0-9 for MP3).

5. Filtering#

You can filter which tracks get synced using Rhai scripts. This allows for powerful, programmable rules to exclude specific content.

To edit the filter script for a destination:

tunz settings filter --destination /path/to/destination

This will open your default editor. You must define a function named filter that takes a track object and returns true (to keep the track) or false (to exclude it).

Available track fields:

• title (String)
• artist (String)
• album (String)
• number (Integer)
• disc_number (Integer)
• disc_total (Integer)
• file_path (String)
• extension (String)

Helper Functions:

• regex_match(pattern, string): Returns true if the string matches the regex pattern.

Examples:

Exclude specific artists and instrumental tracks:

fn filter(track) {
	track.title.make_lower();
	track.artist.make_lower();

	let excluded_artists = [
		"periphery",
		"i built the sky",
		"anup sastry",
		"louis cole",
		"vulfpeck"
	];

	for ea in excluded_artists {
		if track.artist == ea {
			return false
		}
	}

	regex_match("instru*", track.title)
}

Keep only FLAC files:

fn filter(track) {
    return track.extension == "flac";
}

Use Regex to exclude "Live" albums:

fn filter(track) {
    if regex_match("(?i).*live.*", track.album) {
        return false;
    }
    return true;
}

6. Managing Duplicates#

To find albums present in multiple formats within your library:

tunz dupes

7. Cleaning the Library#

If a sync operation is interrupted, some files might be left in an inconsistent state (e.g., partially copied files). You can clean these up using:

tunz clean --destination /path/to/destination

This will search for and remove any tracks in the destination database that are marked as "copying" but never finished.