v0.23.0 bash 3.2 + Go 3 engines ยท 0 new deps

ting / ๅฌ

An agent-first multi-source media engine with a terminal face. Search a source, play it through mpv detached from your terminal, and keep controlling it โ€” from a TUI if you are a human, from a single-line JSON contract if you are a program.

$ brew install binlecode/ting/ting
Install via Homebrew tap on macOS & Linux (or brew tap binlecode/ting && brew install ting)

Two 100% First-Class Faces

No MCP wrapper needed: machine programs and humans interact on equal terms.

Machine Face (Agent-First CLI) JSON Envelope

Designed from day zero for AI agents, shell scripts, and headless automation. Zero modal prompts, deterministic behavior.

  • Single-line JSON envelope output (-j) on every verb
  • Strict 4-tier exit code taxonomy (0 ok / 1 usage / 2+ tool fail / 4 no-op)
  • Detached background playback daemon lifecycle (-d, --status, --stop)
  • Lock-free append-only listening history and durable playlist stores
ting-play --search -j
# Single-line JSON envelope for coding agents
$ ting-play --search -j -n 2 -- "lofi hip hop"
{"event":"search","engine":"yt","query":"lofi hip hop","count":2,"results":[{"id":"jfKfPfyJRdk","title":"lofi hip hop radio","duration":"live"}]}
Human Face (Bubbletea TUI) Single-View

A high-craft Go terminal UI with East-Asian ambiguous width handling, Kitty cover art, and 13 curated themes.

  • Single-view architecture: 6 row sources seamlessly hot-swap into one list
  • Incremental fuzzy filter (/) and row jump navigation (Nj)
  • Destructive actions execute instantly; z undoes without annoying "are you sure" dialogs
  • In-terminal album cover art over Kitty graphics protocol
  • 13 built-in themes (Catppuccin, Tokyo Night, Nord, Rose Pine, Everforest...)
ting (interactive face)
ใ€ ๅฌ ใ€‘ query='lofi hip hop' ยท yt ยท 25 tracks ยท 48k ยท 80%
โ–ถ 01. lofi hip hop radio - beats to relax/study to [03:45]
  02. coffee shop radio // 24/7 lofi hip hop beats [04:12]
  03. 1 A.M Study Session ๐Ÿ“š - [lofi hip hop] [23:10]
โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
Enter ๆ’ญๆ”พ ยท Space ๆš‚ๅœ ยท / ่ฟ‡ๆปค ยท e ๅˆ‡ๆขๆบ ยท z ๆ’ค้”€ ยท ? ๅธฎๅŠฉ

Three Shipped Source Engines

Site-specific knowledge is isolated in engines; the player and TUI never change to admit new sources.

YouTube --engine yt

Direct streams via yt-dlp, quality tier mapping (low / mid / high), start offset normalization, and timestamp extraction.

Features: Search, direct stream, live streams, start offsets, transcript extraction.
Bilibili --engine bili

High-speed curl HTTP metadata extraction paired with yt-dlp stream negotiation and multi-part container (--items) traversal.

Features: Search, multi-part video paging, audio-only extraction, related recommendations.
NetEase Cloud Music --engine ne

Encrypted browser weapi protocol via openssl, real access licensing tiers (full / preview / paywalled), and synced lyrics.

Features: Encrypted search, synchronized lyrics transcript, access flags, high-bitrate audio.

Architecture & Hard Invariants

Seven standalone executables, bash 3.2 baseline, strictly locked to 5 external dependencies.

The suite refuses abstraction sprawl: mpv, yt-dlp, nc -U, curl, and jq are the only external dependencies. No C libraries, no daemon managers, no bloated MCP servers.

+----------------------------------------------------------------------------------------+ | CALLERS & FACES | | [ Agent / Program / CLI ] [ Human Terminal ] | | ting-play --search -j ting (Go Single-View TUI) | +---------------------------+---------------------------------------+--------------------+ | | (Calls CLI verbs) v v +----------------------------------------------------------------------------------------+ | TING-PLAY (The Player & Lifecycle) | | - Detached mpv daemon management: id / pid / unix socket / locks / reap | | - Uniform CLI Envelope (-j) and 4-tier deterministic exit codes | | - Queue consumption & Start offset translation | +---------------------------+---------------------------------------+--------------------+ | | +-------------+-------------+ | Direct audio stream | | v v v +--------------------+ [ Engine Dispatch ] [ Durable Stores ] | mpv (Detached) | ting-engine-yt ting-playlist | - Runs in bg | ting-engine-bili ting-history (jsonl) | - Unix socket IPC | ting-engine-ne (weapi) +--------------------+ +----------------------------------------------------------------------------------------+

Keyboard Navigation

Optimized for terminal ergonomics. Single-stroke actions with instant z undo.

Enter Play focused track
Space Pause / Resume
j / k Navigate up / down
/ Fuzzy filter rows
e Cycle source engine
u Inspect player queue
b Open playlists store
h Listening history log
c / i Parts / Chapters
z Instant Undo
t Cycle 13 Themes
q Quit & cleanup