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:

1. Automatically fetch synced lyrics from online sources
2. Download the audio from YouTube
3. 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 our bash script instead:

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

(Homebrew support coming soon!)

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:

1. Update yt-dlp: pip install -U yt-dlp
2. Check your internet connection
3. Verify the URL is correct
4. 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

1. Check your system audio settings
2. Verify the audio file is valid
3. Try adjusting volume with + or -
4. 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

Copyright © 2026. Licensed under the MIT License. Feel free to use and modify!

Credits

Built with:

• yt-dlp - YouTube downloader
• pygame - Audio playback
• imageio-ffmpeg - FFmpeg binaries
• colorama - Colored terminal output
• PyYAML - YAML parsing

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!