Buzzjam — Lyrics Typewriter Player v3.0

A complete, professional Python application that downloads tracks, plays them, and displays synchronized lyrics with typewriter effects, karaoke mode, web interface, and more!

NEW in v3.0: Karaoke Mode, Auto-Sync Tool, Playlists, Video Export, Web Interface, Spotify/SoundCloud Support, Automated Tests! See all v3.0 features →

** NEWEST: Quick Play** - Just paste a YouTube URL and everything happens automatically! Quick Play Guide →

Quick Play - The Easiest Way!

Just paste a YouTube URL and Buzzjam will:

Automatically fetch synced lyrics from online sources
Download the audio from YouTube
Play with synchronized display instantly!

One Command - That's It!

python quick_play.py "https://youtube.com/watch?v=YOUR_VIDEO_ID"

No manual configuration needed! The system automatically:

Extracts song metadata (artist, title)
Searches multiple lyrics databases
Downloads high-quality audio
Plays with perfectly synced typewriter lyrics

See Quick Play Guide for details →

Features

Audio & Playback

Downloads audio via yt-dlp with automatic MP3 conversion
Precise playback control (play, pause, resume, stop)
Seek forward/backward with keyboard shortcuts
Volume adjustment on-the-fly
Support for local audio files (MP3, WAV, OGG, FLAC, M4A)

Lyrics & Display

Typewriter effect with real-time sync to audio
LRC file format support for standard lyrics files
Preview upcoming lyrics
Colored terminal output for enhanced visuals
Real-time progress and timing display
Live lyric offset adjustment (±0.25s increments)

Configuration

YAML configuration files for easy customization
Command-line arguments for quick operations
Export configurations for reuse
Multiple songs and playlists support

Developer Features

Modular architecture for easy extension
Type hints throughout codebase
Test-ready structure
Backward compatible with v1.0

Requirements

Python 3.11+
Virtual environment (recommended)

Quick Start

The easiest way to install Buzzjam is via npm. It will automatically handle downloading and isolating all Python dependencies for you!

npm install -g @nikanjuri/buzzjam

Don't have Node.js? Use Homebrew (macOS/Linux):

brew tap nikanjuri/tap
brew install buzzjam

Or use our universal bash script:

curl -fsSL https://raw.githubusercontent.com/nikanjuri/buzzjam/main/install.sh | bash

Channel release details: DISTRIBUTION.md

Available CLI Commands

After install, these commands are available:

buzzjam --help
buzzjam play --file my_song.mp3 --lyrics song.lrc
buzzjam fetch-lyrics "https://youtube.com/watch?v=..." --json
buzzjam web --host 127.0.0.1 --port 5000
buzzjam web --no-open  # headless/server mode
buzzjam-sync my_song.mp3 --output synced_lyrics.lrc

If the selected web port is already in use, Buzzjam automatically picks a free port and prints the final URL.

For machine integrations, play can stream structured events:

buzzjam play --file my_song.mp3 --lyrics song.lrc --events-jsonl --non-interactive
buzzjam play --file my_song.mp3 --events-file ./logs/buzzjam.jsonl --non-interactive
buzzjam play --file my_song.mp3 --events-jsonl --event-types playback.started,lyrics.line_started

Event contract reference: EVENTS.md

Python applications can also run playback directly:

from buzzjam import Config, PlaybackSession
from buzzjam.playback_session import jsonl_event_printer

cfg = Config()
cfg.song.local_file = "my_song.mp3"
cfg.lyrics_file = "song.lrc"

session = PlaybackSession(cfg, event_handler=jsonl_event_printer, interactive=False)
ok = session.run()

Run with Defaults

# Using the new modular version
.venv/bin/buzzjam play

# Or activate venv first
source .venv/bin/activate
buzzjam play

Run with Custom Options

# Use a config file
buzzjam play --config my_song.yaml

# Specify YouTube URL and lyrics
buzzjam play --url "https://youtube.com/..." --lyrics song.lrc

# Use local file with custom start time
buzzjam play --file my_song.mp3 --lyrics song.lrc --start 30

# Quick play with title
buzzjam play --url "..." --title "My Favorite Song" --lyrics song.lrc

Backward Compatibility

The original script still works:

.venv/bin/python buzzjam.py

Controls

Once the player is running, use these keyboard commands:

Key	Action	Description
`p`	Pause	Pause playback
`r`	Resume	Resume playback
`[`	Earlier	Make lyrics appear 0.25s earlier
`]`	Later	Make lyrics appear 0.25s later
`,`	Skip Back	Skip backward 5 seconds
`.`	Skip Forward	Skip forward 5 seconds
`-`	Volume Down	Decrease volume by 10%
`+` or `=`	Volume Up	Increase volume by 10%
`o`	Show Offset	Display current lyric offset
`h` or `?`	Help	Show available commands
`s` or `q`	Stop	Stop playback and quit

Configuration Files

YAML Config Example

Create a config.yaml file:

song:
  youtube_url: "https://www.youtube.com/watch?v=..."
  local_file: ""  # Or path to local file
  start_time: 0
  title: "My Awesome Song"

playback:
  char_delay: 0.12        # Typewriter speed
  sample_rate: 44100      # Audio quality
  volume: 1.0             # 0.0 to 1.0

display:
  show_time: true         # Show playback time
  show_progress: true     # Show progress percentage
  show_preview: true      # Show upcoming lyrics
  preview_lines: 2        # Number of preview lines
  colored_output: true    # Use colors

lyrics_file: "lyrics.lrc"
output_dir: "."

Then run:

buzzjam play --config config.yaml

LRC Lyrics Format

Create lyrics in standard LRC format (song.lrc):

[00:12.00]First line of lyrics
[00:15.50]Second line with decimal seconds
[01:23.00]Minute and seconds format

LRC Format Guide:

Timestamps: [MM:SS.ss]
Minutes: 2 digits
Seconds: 2 digits
Centiseconds: Optional, 2 digits
Text after timestamp

Project Structure

buzzjam/
├── buzzjam/              # Main package
│   ├── __init__.py          # Package exports
│   ├── config.py            # Configuration management
│   ├── downloader.py        # YouTube/audio download
│   ├── player.py            # Audio playback engine
│   ├── lyrics.py            # Lyrics parsing & sync
│   └── controls.py          # Input & display management
├── buzzjam.py            # Legacy script (v1.0)
├── config.example.yaml       # Example configuration
├── lyrics.lrc                # Example lyrics file
├── .gitignore                # Git exclusions
└── README.md                 # This file

Features in Detail

Typewriter Effect

The typewriter effect synchronizes character-by-character with the music:

Smart timing: Calculates how many characters should be visible based on elapsed time
Pause-aware: Automatically pauses when music pauses
Offset adjustment: Fine-tune timing on-the-fly with [ and ] keys

Preview Mode

See what's coming next:

Currently typing: This is the current line...

Upcoming:
  ↓ Next line preview
  ↓ Line after that

Status Display

Real-time information during playback:

[02:15] Progress: 45% | Offset: -0.50s

Advanced Usage

Export Your Configuration

Save your settings for reuse:

buzzjam play --url "..." --lyrics song.lrc --export-config my_config.yaml

Disable Colors

For terminals without color support:

buzzjam play --no-color

Create Custom Lyrics

You can create .lrc files manually or use online LRC editors:

LRC Editor Online
Or use the typewriter effect to time them yourself!

Troubleshooting

YouTube Rate Limits / Bot Blocks (Silent Hangs)

YouTube aggressively blocks automated scripts (yt-dlp and spotdl). If your downloads are silently hanging forever or instantly failing with HTTP 429, you have been rate-limited.

To bypass this, Buzzjam automatically detects your primary installed web browser (Safari, Chrome, Firefox, Edge, or Brave) and securely borrows its local cookies so YouTube trusts the download request. No manual setup is required!

(Disclaimer: This extracts YouTube cookies locally to authenticate your request. If you have privacy concerns and wish to disable this behavior, you can run export BUZZJAM_BROWSER="off").

"No module named 'pygame'"

Make sure you're using the virtual environment Python:

.venv/bin/buzzjam play
# Ensure your environment is active

Download fails

If YouTube download fails:

Update yt-dlp: pip install -U yt-dlp
Check your internet connection
Verify the URL is correct
Try using a local file instead

Lyrics out of sync

Use the live adjustment controls:

Press [ to make lyrics appear earlier
Press ] to make lyrics appear later
Each press adjusts by 0.25 seconds
Press o to see current offset

No audio output

Check your system audio settings
Verify the audio file is valid
Try adjusting volume with + or -
Check if file exists: ls -la song.mp3

Development

Running Tests

# TODO: Add tests
python -m pytest tests/

Code Structure

The codebase follows these principles:

Separation of Concerns: Each module has a single responsibility
Type Safety: Type hints throughout
Error Handling: Graceful degradation
Extensibility: Easy to add new features

Adding New Features

To add a new control command:

# In buzzjam/playback_session.py, BuzzjamPlayer._setup_controls()
self.controls.register_command('x', self.my_function, "Description")

Contributing

Contributions welcome! Areas for improvement:

Add tests
Support more audio sources (Spotify, SoundCloud)
Karaoke mode with word-level highlighting
Web interface
Lyrics editing tool

License

Credits

Built with:

yt-dlp - YouTube downloader
pygame - Audio playback
imageio-ffmpeg - FFmpeg binaries
colorama - Colored terminal output
PyYAML - YAML parsing
https://github.com/niralverma - Inspiration from code_wishes

Enjoy!

Now sit back, relax, and enjoy your music with synchronized lyrics!

For questions or issues, please open an issue on GitHub.

Pro Tip: Create a collection of .lrc files for your favorite songs and keep them organized in a lyrics/ folder!

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
bin		bin
buzzjam		buzzjam
packaging/homebrew		packaging/homebrew
scripts		scripts
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
DISTRIBUTION.md		DISTRIBUTION.md
EVENTS.md		EVENTS.md
FEATURES_V3.md		FEATURES_V3.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
QUICK_PLAY_GUIDE.md		QUICK_PLAY_GUIDE.md
README.md		README.md
config.example.yaml		config.example.yaml
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Buzzjam — Lyrics Typewriter Player v3.0

Quick Play - The Easiest Way!

One Command - That's It!

Features

Audio & Playback

Lyrics & Display

Configuration

Developer Features

Requirements

Quick Start

Available CLI Commands

Run with Defaults

Run with Custom Options

Backward Compatibility

Controls

Configuration Files

YAML Config Example

LRC Lyrics Format

Project Structure

Features in Detail

Typewriter Effect

Preview Mode

Status Display

Advanced Usage

Export Your Configuration

Disable Colors

Create Custom Lyrics

Troubleshooting

YouTube Rate Limits / Bot Blocks (Silent Hangs)

"No module named 'pygame'"

Download fails

Lyrics out of sync

No audio output

Development

Running Tests

Code Structure

Adding New Features

Contributing

License

Credits

Enjoy!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages