openaudio

Stream listening-first audio in the terminal from YouTube, Twitch, X, and other yt-dlp-supported sites.

It uses:

• yt-dlp for media extraction
• mpv for the best playback experience when available
• ffplay as a fallback player

Features

• audio-first playback
• quiet, low-latency defaults
• clean interactive terminal UI
• YouTube search with a metadata-aware picker
• direct URL playback for Twitch, X, and other supported sites
• TypeScript codebase with explicit module boundaries
• live now-playing metadata from mpv IPC
• in-app seek, pause, and volume control

Requirements

Install yt-dlp and one player:

brew install yt-dlp mpv ffmpeg

mpv is strongly recommended. ffplay comes from ffmpeg.

Install

Local development:

npm install
npm run build
npm run start

This app's TUI runtime uses Bun through OpenTUI. node dist/index.js is not the correct launch command.

After publishing:

npm install -g openaudio

Usage

Open the interactive prompt:

npm run start

Play a direct YouTube URL:

openaudio "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Search YouTube from the CLI:

openaudio "boards of canada"

Play a Twitch or X URL:

openaudio "https://www.twitch.tv/videos/123456789"
openaudio "https://x.com/i/status/123456789"

Force a player:

openaudio --player mpv "burial archangel"

Choose the search site explicitly:

openaudio --site youtube "four tet"

Change result count:

openaudio --limit 15 "aphextwin"

Doctor check:

openaudio --doctor

Notes

• Search is YouTube-first in this version.
• Twitch and X are supported via direct URLs.
• You do not need to keep a browser tab open.
• Audio-only playback usually uses less bandwidth than full video playback.

Repo Layout

src/
  cli/        argument parsing and help text
  commands/   top-level commands like doctor
  media/      yt-dlp search and media metadata normalization
  opentui/    terminal UI, formatting, and theme
  player/     mpv integration and playback state
  utils/      process and terminal helpers

The intent is strict separation:

• index.tsx boots the runtime
• media knows remote content shape
• player knows local player behavior
• opentui only handles terminal interaction and presentation
• utils stays generic

TUI Controls

• enter: run search or play selected item
• tab: switch focus
• up / down: move results
• space: pause/resume
• left / right: seek
• + / -: volume
• q / x / ctrl+c: stop or quit

Publish

Before publishing, update the package metadata in package.json:

• name
• version
• author

Then publish:

npm login
npm publish

If the package name is taken, rename it before publishing.

ytaudio is still exposed as a compatibility alias for local installs.