Playback

A terminal-based audio player with synchronized transcript viewing and editing.

Quick Start

playback audio.mp3                    # Auto-finds transcript (audio.srt)
playback audio.mp3 -t transcript.srt  # Specify transcript

Features

• Multi-format Audio Support: Play MP3, WAV, FLAC, OGG files
• Synchronized Transcripts: Display and highlight SRT subtitles synced with audio
• Vim-style Editing: Edit transcripts using external editor (vim/nvim/emacs/etc)
• Waveform Visualization: Visual seek controls with progress indication
• Auto Transcript Discovery: Automatically finds matching .srt files
• Configurable Keybindings: Customizable shortcuts for all actions

Installation

Prerequisites

• Go 1.25.4 or higher
• Standard Linux tools (for desktop entry: update-desktop-database)

No additional native dependencies required - all dependencies are Go modules.

Build from Source

# Clone the repository
git clone <repo-url>
cd playback

# Install Go dependencies
go mod download

# Build
make build

# Run
./build/playback audio.mp3

Install to System

# Build and install
make install

# Or using the install script
./install.sh

Playback will be installed to /usr/local/bin/playback and a desktop entry created for your application menu.

Usage

Basic Usage

# Auto-detect transcript
playback audio.mp3

# Specify transcript file
playback audio.mp3 -t transcript.srt

# Run from system
playback audio.mp3

Transcript Auto-Discovery

Playback automatically searches for a transcript file by:

1. Using the filename without extension (e.g., audio.mp3 → audio.srt)
2. If not found, prompts you to specify a path

Editor Configuration

Configure your preferred external editor in the config file (see Configuration below).

Keybindings

Key	Action
q	Quit
?	Toggle help
space	Play/Pause
ctrl+j	Focus transcript view
ctrl+k	Focus waveform view

Waveform View (When Focused)

Key	Action
h / l or ← / →	Seek 5 seconds
H / L	Seek 30 seconds
g	Jump to beginning
G	Jump to end

Transcript View (When Focused)

Key	Action
j / k	Navigate to previous/next cue
ctrl+d	Jump 5 cues down
ctrl+u	Jump 5 cues up
g	Jump to first cue
G	Jump to last cue
enter	Seek audio to current cue position
i	Edit transcript in external editor

Configuration

Create a config file at ~/.config/playback/config.json:

{
  "seek_step_ms": 5000,
  "big_seek_step_ms": 30000,
  "volume": 1.0,
  "editor": "nvim"
}

Configuration Options

Option	Type	Default	Description
seek_step_ms	integer	5000	Seek step in milliseconds (small jumps)
big_seek_step_ms	integer	30000	Big seek step in milliseconds (large jumps)
volume	float	1.0	Initial volume level (0.0 - 1.0)
editor	string	"vim"	External editor command to use

Troubleshooting

Audio Not Playing

Ensure your audio files are supported (MP3, WAV, FLAC, OGG).

Transcript Not Found

Specify the transcript file explicitly with -t flag:

playback audio.mp3 -t path/to/transcript.srt

Desktop Entry Not Appearing

Run update-desktop-database ~/.local/share/applications after installation.

Project Setup for Developers

# Clone the repository
git clone <repo-url>
cd playback

# Install Go dependencies
go mod download

# Build
make build

# Run
make run ./audio.mp3

# Run tests
make test

# Clean build artifacts
make clean

License

[Add your license here]