179 lines
3.7 KiB
Markdown
179 lines
3.7 KiB
Markdown
# Playback
|
|
|
|
A terminal-based audio player with synchronized transcript viewing and editing.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```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:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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] |