Project

tucue

0.0
The project is in a healthy, maintained state
tucuetakkanm/tucueHomepageDocumentationSource CodeBug TrackerWiki
tucue plays local audio files (mp3/wav) in a terminal UI, lets you mark timestamps with optional labels, and export them as CSV or JSON. Playback is delegated to mpv.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
233
Stars
0
Forks
0
Watchers
0
 Releases
Current version
0.1.0
Total releases
1
First release
2026-06-06
Latest release
2026-06-06
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-06-06
Reverse Dependencies
0

 Dependencies

Runtime

csv
~> 3.0
curses
~> 1.4
 Project Readme

tucue

CI

A Ruby TUI application for playing local audio files, marking specific moments, and exporting them. Handy for managing cue points in interview recordings and similar audio.

The name is a blend of TUI and Cue (pronounced "too-cue").

┌─────────────────────────────────┐
│  File: interview.mp3            │
│  00:01:23 / 00:45:10  ####----  │
├─────────────────────────────────┤
│  [Space] play/pause             │
│  [<-] -5s   [->] +5s            │
│  [[] -15s   []] +15s            │
│  [m] mark   [e] export          │
│  [q] quit                       │
├─────────────────────────────────┤
│  Marks (2)                      │
│  * 00:01:23 - key point         │
│  * 00:03:45                     │
└─────────────────────────────────┘

Features

  • Play audio files such as mp3 / wav
  • Rewind and fast-forward in 5- and 15-second steps
  • Mark the current position with an optional label
  • Export the mark list as CSV or JSON

Requirements

  • macOS (developer environment)
  • Ruby 3.x or later
  • mpv (used as the playback engine)
brew install mpv

Installation

Clone the repository and run bundle install.

git clone https://github.com/takkanm/tucue.git
cd tucue
bundle install

Usage

bundle exec tucue interview.mp3

This launches the TUI and starts playback.

Options

Option Description
-s, --start TIME Start playback at TIME. Accepts SS, MM:SS, or HH:MM:SS (e.g. 90, 1:30, 01:02:03).
-v, --version Show the version.
-h, --help Show help. 
bundle exec tucue --start 01:02:03 interview.mp3

Key bindings

Key Action
Space / p Play / pause
→ +5 seconds
← -5 seconds
] +15 seconds
[ -15 seconds
m Mark the current position (prompts for an optional label)
e Export the marks
q Quit

Export

Pressing e writes the current marks to a .csv file named after the audio file.

CSV

timestamp,seconds,label
00:01:23,83.0,key point
00:03:45,225.5,

JSON

JSON export is also supported (Tucue::Marker#export_json).

[
  {
    "timestamp": "00:01:23",
    "seconds": 83.0,
    "label": "key point"
  },
  {
    "timestamp": "00:03:45",
    "seconds": 225.5,
    "label": null
  }
]

Architecture

File Responsibility
bin/tucue CLI entry point
lib/tucue/player.rb Playback engine controlling mpv over JSON IPC (Unix socket)
lib/tucue/ui.rb curses-based TUI and key-input loop
lib/tucue/marker.rb Mark management and CSV / JSON export

mpv is launched with --input-ipc-server and controlled by sending JSON commands over a Unix domain socket to seek and read the playback position.

License

tucue is released under the MIT License.

tucue requires mpv, which is licensed under GPL-2.0-or-later and LGPL-2.1-or-later. mpv runs as a separate process and is not distributed with tucue; you install it yourself (e.g. via Homebrew), so its copyleft terms do not apply to tucue's own source.