VinylKit Manual

VinylKit

GitHub tag (latest SemVer)
Documentation

VinylKit is a cross-platform CLI tool for managing digitized vinyl record audio files using metadata from Discogs. It helps you tag, organize, and maintain your collection with high-quality metadata.

Features

  • Discogs Integration: Fetch high-quality metadata (Genres, Styles, Notes) using Release IDs or interactive search.
  • Combined Workflow: Tag, rename and move files to your library in a single step.
  • Support for MP3 and FLAC: Comprehensive tagging for ID3v2 and Vorbis comments.
  • Vinyl-Specific Metadata: Preserves vinyl-specific info like side (A/B) and position (A1, B2).
  • Metadata Export: Automatically creates a release_info.txt file in every tagged album folder with all the discogs release info.
  • Safe Operations: Optional dry-runs, filename sanitization, and atomic file moves.
  • Batch Processing: Use --batch to automatically tag multiple folders, extracting Discogs IDs from folder names.
  • Artwork Management: Embed album art directly into audio files (retrieved from Discogs).
  • Flexible Organization: Use customizable naming templates to organize your library.
  • Collection Export: Download your entire Discogs collection to a local CSV file.

Installation

There are a few ways to install VinylKit. Pick the one that fits your setup:

Option 1: Standalone Installer

This doesn't require Python or any package managers. The script automatically detects your system and installs a pre-compiled binary:

  • macOS & Linux (Bash/Zsh):
    bash curl -fsSL https://vinylkit.app/install.sh | bash
  • Windows (PowerShell):
    powershell irm https://vinylkit.app/install.ps1 | iex

Option 2: Python / Developer Tool (uv)

If you already have Python and uv installed, you can install it as a global tool:

uv tool install git+https://github.com/alaninspace/vinyl-kit.git

For other installation options—including manual PyInstaller executables, PyApp bootstrappers, Homebrew, and Scoop—see the full Download & Install Guide.

Quick Start

  1. Set your library location (where tagged music ends up):

bash vinylkit config set library_root "/path/to/VinylLibrary"

  1. Set your recordings inbox (where new vinyl recordings are placed):

bash vinylkit config set recordings_root "/path/to/RecordedVinyl"

  1. Set your Discogs token (generate one here):

bash vinylkit config set discogs_token "YOUR_TOKEN"

  1. Scan and tag:

bash vinylkit scan vinylkit tag --id 19983

[!TIP]
For OAuth setup, naming patterns, and other configuration settings, see the Quickstart Guide.

Configuration

Settings are stored in a TOML file. You can view your current configuration with:

vinylkit config show

For more details, check out vinylkit.app or see these local files: