feat: unified navigation
fix: install script copying build binary chore: updated readme
This commit is contained in:
169
README.md
169
README.md
@@ -2,43 +2,119 @@
|
||||
|
||||
A terminal-based audio player with synchronized transcript viewing and editing.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
make install
|
||||
```
|
||||
|
||||
## Usage
|
||||
## 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 |
|
||||
|-----|--------|
|
||||
| `space` | Play/Pause |
|
||||
| `ctrl+j` | Focus transcript |
|
||||
| `ctrl+k` | Focus waveform |
|
||||
| `q` | Quit |
|
||||
| `?` | Toggle help |
|
||||
| `space` | Play/Pause |
|
||||
| `ctrl+j` | Focus transcript view |
|
||||
| `ctrl+k` | Focus waveform view |
|
||||
|
||||
**Waveform (focused):**
|
||||
- `h/l` or arrows: Seek 5s
|
||||
- `H/L`: Seek 30s
|
||||
### Waveform View (When Focused)
|
||||
|
||||
**Transcript (focused):**
|
||||
- `j/k`: Navigate cues
|
||||
- `ctrl+d/u`: Jump 5 cues
|
||||
- `g/G`: First/last cue
|
||||
- `enter`: Seek audio to cue
|
||||
- `i`: Edit in external editor
|
||||
| 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
|
||||
|
||||
Config file: `~/.config/playback/config.json`
|
||||
Create a config file at `~/.config/playback/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -49,4 +125,55 @@ Config file: `~/.config/playback/config.json`
|
||||
}
|
||||
```
|
||||
|
||||
Default editor is `vim`.
|
||||
### 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]
|
||||
Reference in New Issue
Block a user