npm package: @nikanjuri/buzzjam
Description: Global npm wrapper for the Buzzjam Python CLI
Latest version: 3.0.0

# 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 →**](FEATURES_V3.md)

> ** NEWEST: Quick Play** - Just paste a YouTube URL and everything happens automatically! [**Quick Play Guide →**](QUICK_PLAY_GUIDE.md)

![Version](https://img.shields.io/badge/version-3.0-blue)
![Python](https://img.shields.io/badge/python-3.11+-green)
![License](https://img.shields.io/badge/license-MIT-orange)

---

##  **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!

```bash
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 →**](QUICK_PLAY_GUIDE.md)

---


##  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!

```bash
npm install -g @nikanjuri/buzzjam
```

*Don't have Node.js? Use our bash script instead:*
```bash
curl -fsSL https://raw.githubusercontent.com/nikanjuri/buzzjam/main/install.sh | bash
```

*(Homebrew support coming soon!)*

Channel release details: [DISTRIBUTION.md](DISTRIBUTION.md)

### Available CLI Commands

After install, these commands are available:

```bash
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:

```bash
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](EVENTS.md)

Python applications can also run playback directly:

```python
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

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

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

### Run with Custom Options

```bash
# 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:

```bash
.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:

```yaml
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:

```bash
buzzjam play --config config.yaml
```

### LRC Lyrics Format

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

```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:

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

### Disable Colors

For terminals without color support:

```bash
buzzjam play --no-color
```

### Create Custom Lyrics

You can create `.lrc` files manually or use online LRC editors:
- [LRC Editor Online](https://lrc-maker.github.io/)
- 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:

```bash
.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

```bash
# 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:

```python
# 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](LICENSE). Feel free to use and modify!

##  Credits

Built with:
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - YouTube downloader
- [pygame](https://www.pygame.org/) - Audio playback
- [imageio-ffmpeg](https://github.com/imageio/imageio-ffmpeg) - FFmpeg binaries
- [colorama](https://github.com/tartley/colorama) - Colored terminal output
- [PyYAML](https://pyyaml.org/) - 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!