ZIM Studio - Terminal-Based Audio Tools

A Zettelkasten Information System for Music Production with Integrated Audio Player

Implemented in Rust and Ratatui with optional nvim plugin support.

ZIM Studio provides three main functions:

1. Project Management: Initialize a project structure of directories and placeholder README.md files
2. Metadata System: Generate searchable sidecar files for all audio media
3. Audio Player: Sample browsing, auditioning, and editing with TUI interface

✨ More...

• Supported Audio Formats: *.flac and *.wav (so far)
• Enhanced Navigation: Shift+Arrow keys for 20% jumps through long recordings
• Smart Sidecar Cloning: When saving selections, automatically clones source metadata with:
  • Updated duration for the extracted selection
  • Provenance tracking (source file, time ranges)

The sidecar format is YAML embedded in markdown, providing both structured metadata and free-form notes. The YAML contains facts about the track while the markdown enables long-form notes, links to inspiration, TODO checklists, etc.

See example sidecar file for a complete example.

The motivation for creating zim is twofold:

1. Maintain a workflow where DAWs are guests in my workflow rather than the other way around.
2. I use neovim and telescope for my personal note taking and rely on no proprietary company to enable my ability to work in software ... I wanted the same detailed note taking independent of any vendor for my music making. I use proprietary DAWs but am not ok living in DAWs or any vendor's closed system.

Installation

# Install with full features (includes audio player)
cargo install zim-studio

# Install minimal version without audio player (scaffold and metadata only)
cargo install zim-studio --no-default-features

If you use neovim (untested with regular vim) you may want to try the nvim plugin.

Quick Start

# Initialize ZIM with your music projects directory
zim init ~/Music/Projects

# Create a new project
zim new "My Greatest Hits"
# Creates: ~/Music/Projects/my_greatest_hits/

# Navigate to your project and add some audio files
cd ~/Music/Projects/my_greatest_hits
cp ~/Desktop/track1.flac masters/
cp ~/Desktop/track2.wav masters/

# Generate sidecar metadata files
zim update .
# Creates: masters/track1.flac.md, masters/track2.wav.md

# Edit the generated sidecar files to add your notes
$EDITOR masters/track1.flac.md

# Validate all YAML frontmatter
zim lint .

# View/edit global configuration
zim config view
zim config edit

Project Structure

When you create a new project with zim new, it generates:

my_greatest_hits/
├── .gitignore          # Ignores audio/video files
├── README.md           # Project overview
├── masters/            # Final mastered tracks
├── mixes/              # Mix versions
├── sources/            # Raw recordings, samples
├── edits/              # Edited/comped audio
├── bounced/            # Bounced/rendered audio (stems, etc)
└── project/            # DAW project files
    ├── live/           # Ableton Live
    ├── reaper/         # Reaper
    ├── bitwig/         # Bitwig Studio
    └── renoise/        # Renoise

Sidecar Files

zim update generates a .md sidecar for each audio file with:

• YAML frontmatter: Structured metadata (technical specs, tags, etc.)
• Markdown body: Free-form notes, ideas, TODO lists
• Automatic tag inference: Tags are automatically added based on filename patterns (e.g., files with "ES-9" get tagged "eurorack", "drum" files get tagged "drums")

The YAML is designed to be both human-editable and scriptable for automation. See the example sidecar for what this looks like in practice.

Automatic Tag Inference

ZIM automatically infers tags from filenames using configurable pattern mappings. Default mappings include:

• Hardware: ES-9 → eurorack, modular → eurorack
• Instruments: drum → drums, bass → bass, synth → synth
• Structure: loop → loop, kick → drums, snare → drums
• Vocals: vocal → vocals, vox → vocals
• DAWs: ableton → ableton-live, reaper → reaper

To customize tag mappings, edit ~/.config/zim/config.toml:

[tag_mappings]
"ES-9" = "eurorack"
"my-pattern" = "my-tag"
"field-rec" = "field-recording"

Note: If you have an existing config file, the default tag mappings will still work automatically - no migration needed!

WAV Metadata Tagging

ZIM can embed metadata directly into WAV files using INFO LIST chunks. This metadata includes UUIDs for unique identification and lineage tracking across your DAW workflows.

Tag Commands

zim tag add - Tag a copy of the file

Creates a new WAV file with _tagged suffix containing embedded metadata. The original file remains unchanged.

# Tag a WAV file (creates kick_tagged.wav)
zim tag add kick.wav

# Specify project explicitly (otherwise auto-detected from .zimignore)
zim tag add kick.wav --project "my-album"

zim tag edit - Tag in-place

Updates the original WAV file directly with embedded metadata. Creates a backup in /tmp by default.

# Update metadata in the original file
zim tag edit kick.wav

# Skip backup creation (use with caution)
zim tag edit kick.wav --no-backup

zim tag derive - Create derived file with lineage

Creates a new WAV file that tracks its relationship to the source file. Perfect for tracking exports, bounces, and transformations.

# Create a derived file (e.g., after processing in a DAW)
zim tag derive original.wav processed.wav --transform "eq+compress"

# Common transform types: excerpt, mix, master, bounce, process
zim tag derive full_take.wav intro_only.wav --transform "excerpt"

zim tag info - Read embedded metadata

Displays any ZIM metadata embedded in a WAV file.

# Check if a WAV file has metadata
zim tag info some_file.wav

Metadata Fields

Each tagged WAV file contains:

• UUID: Unique identifier for the file
• Parent UUID: Link to source file (for derived files)
• Project: Associated project name
• Generation: How many transformations from the original (0 = original)
• Transform: Type of processing applied (for derived files)
• Audio MD5: Fingerprint of the audio data
• First Seen: ISO 8601 timestamp when first tagged
• Original Path: Where the file was first tagged

Integration with zim update

The zim update command automatically tags any untagged WAV files it encounters, embedding metadata directly into the files. The UUID is also included in the generated markdown sidecar files for cross-referencing.

# Recursively process directory, auto-tagging WAV files
zim update .

Use Cases

1. Import Tracking: When importing WAV files into a DAW, they retain their identity
2. Export Lineage: Track which files were derived from which sources
3. Collaboration: Share WAV files that carry their own provenance
4. Deduplication: Identify the same audio even if files are renamed
5. Project Organization: Find all files belonging to a specific project

Note: If you have an existing config file, the default tag mappings will still work automatically - no migration needed!

Shell Completions

Add to your shell configuration:

# Bash (~/.bashrc)
source <(zim completions bash)

# Zsh (~/.zshrc)
source <(zim completions zsh)

# Fish (~/.config/fish/config.fish)
zim completions fish | source

# PowerShell ($PROFILE)
zim completions powershell | Out-String | Invoke-Expression

Development

# Run all checks locally (matches CI)
make ci

# Individual commands
make fmt        # Format code
make clippy     # Run lints
make test       # Run tests
make check      # Check compilation

Audio Player User Guide

The optional audio player provides a fast, keyboard-driven interface for browsing, auditioning, and editing audio samples directly from the terminal.

Launching the Player

# Launch with no file (opens browser)
zim player

# Launch with a specific audio file
zim player path/to/audio.wav

Main Interface

The player interface consists of:

• Title Bar: Shows "🎵 ZIM Player"
• File Info & LEDs: Current file name and stereo level indicators
• Progress Bar: Playback position with mark in/out indicators
• Oscilloscope: Real-time waveform visualization (when window is tall enough)
• Control Hints: Two rows of keyboard shortcuts

Keyboard Controls

Playback Controls

• [space] - Play/Pause toggle
• [←] - Seek backward 5 seconds
• [→] - Seek forward 5 seconds
• [Shift+←] - Jump backward 20% (great for long recordings)
• [Shift+→] - Jump forward 20% (great for long recordings)

Mark & Loop Controls

• [i] - Set mark in at current position
• [o] - Set mark out at current position
• [x] - Clear all marks
• [l] - Toggle loop playback of marked selection

File Operations

• [/] - Open file browser
• [e] - Edit sidecar metadata in external editor ($EDITOR)
• [s] - Save/export (full file or marked selection)
• [q] - Quit player

File Browser

The built-in file browser searches through your audio files using their sidecar .md metadata:

1. Press / to open the browser
2. Use [↑/↓] or [j/k] to navigate files
3. Press / again to show search overlay
4. Type to search - it searches within the markdown content of sidecar files
5. Press [Enter] or [Esc] to hide search and return to file list
6. Press [Enter] on a file to load it
7. Press [Esc] to close browser

Note: The browser displays audio files but searches their .md sidecar content. For example, if you have kick.wav with kick.wav.md containing "punchy 808 style", searching for "808" will find this file.

Mark In/Out & Looping

The mark feature lets you select a portion of the audio:

1. Play the file and press [i] at the desired start point
2. Press [o] at the desired end point
3. The selection appears highlighted on the progress bar
4. Press [l] to loop the selection continuously
5. The time display shows selection duration in brackets: [3.5s]

Save Dialog

When saving ([s]), the save dialog provides:

• Directory Browser: Navigate folders with [↑/↓] and [Enter]
• Filename Field: Editable with smart naming for edits
• Tab Navigation: Use [Tab] to switch between directory list and filename
• Smart Extensions:
  • Selections always save as .wav (even from FLAC sources)
  • Full file saves preserve original format

Example auto-generated filenames:

• First edit: original_edit.wav
• Subsequent edits: original_edit_2.wav, original_edit_3.wav, etc.

LED Level Indicators

[IMAGE: Close-up of LED indicators showing different levels]

The stereo LED indicators show real-time audio levels:

• L (Left): Green LEDs - dim → medium → bright → red (clipping)
• R (Right): Orange LEDs - dim → medium → bright → red (clipping)
• Symbols: ○ (off/quiet) → ◐ (medium) → ● (loud)

Supported Formats

• WAV: 8, 16, 24, and 32-bit
• FLAC: All bit depths (converted to 16-bit WAV when saving selections)
• AIFF: All bit depths with intelligent sample rate detection WIP

Tips & Workflow

1. Quick Sample Chopping: Load file → mark in/out → save = done
2. Preview Before Save: Use [l] to loop your selection before saving
3. Rapid Browsing: The browser remembers your search, making it fast to audition similar samples
4. Long Recording Navigation: Use Shift+Arrow for 20% jumps to quickly navigate through long recordings
5. Metadata Preservation: When saving selections, source metadata is automatically cloned with updated duration and provenance tracking
6. No Mouse Needed: Everything is keyboard-driven for speed
7. Mix Multiple Files: Audition up to 3 files simultaneously with individual gain control:

   # Mix with equal volume
   zim play drums.wav bass.wav vocals.wav
   
   # Mix with custom gains (0.0-2.0 range)
   zim play drums.wav bass.wav vocals.wav --gains 0.8,1.2,0.6
   

   See mixing guide for detailed examples

Troubleshooting

• No Audio: Check system audio output settings
• Browser Not Finding Files: Ensure .md sidecar files exist (run zim update)
• Visual Glitches: Resize terminal window or restart player

License

MIT