1// Buzzjam.md
2// ---------------------------
3
4# Buzzjam
5
6Python lyrics player with synced typewriter display — paste a YouTube URL and get auto-fetched lyrics, audio download, karaoke mode, and a Flask web player.
7
8**TYPE:** Python Application (CLI + Web)
9**STATUS:** Open Source
10**DEV:** http://localhost:5100
11**WORKSPACE:** ~/GitHub/buzzjam
12**REPO:** https://github.com/nikanjuri/buzzjam
13
14---
15
16## FEATURES
17
18- Quick Play — paste a YouTube URL; lyrics are fetched, audio downloaded, playback starts automatically
19- Typewriter and karaoke modes with word-level highlighting synced to audio
20- Flask web player with search, queue, shuffle/repeat, lyric offset tuning, and AI karaoke toggle
21- Auto-sync tool for creating LRC timing interactively
22- Playlist support (JSON/M3U) with shuffle and repeat modes
23- Video export — lyrics rendered to MP4 in three styles
24- Spotify and SoundCloud download via spotdl and yt-dlp
25- Published on npm as `@nikanjuri/buzzjam` with a pytest suite (58 tests)
26
27---
28
29## TECHNOLOGIES
30
31- Python 3.11+
32- Flask
33- yt-dlp
34- pygame
35- pytest
36- npm (global CLI wrapper)
37
38---
39
40## NOTES
41
42Buzzjam downloads tracks, plays them, and displays synchronized lyrics with a typewriter effect — from a one-command terminal session or a full web player.
43
44### Quick Play
45
46Paste a YouTube URL and Buzzjam handles the rest: extract song metadata, search multiple lyrics databases (preferring synced LRC), download and convert audio, and start playback with perfectly timed lyrics. No manual config.
47
48### Beyond the terminal
49
50v3 adds karaoke mode with word-level highlighting, an interactive auto-sync tool for building LRC files, playlist support, MP4 video export, and a Flask web player with search, queue management, live offset adjustment, and an AI karaoke toggle. Spotify and SoundCloud sources work through spotdl and yt-dlp.
51
52### Shipped as a product
53
54The project is modular (type hints throughout), covered by 58 pytest tests, and published globally via `npm install -g @nikanjuri/buzzjam`, which wraps the Python CLI without requiring manual venv setup.