@nikanjuri/buzzjam-cli 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikhil Anjuri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,403 @@
+# 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-cli
+```
+
+*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!

package/bin/buzzjam.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+const os = require("node:os");
+const fs = require("node:fs");
+
+const repoSpec = process.env.BUZZJAM_INSTALL_SPEC || "git+https://github.com/nikanjuri/buzzjam.git";
+const pythonBin = process.env.PYTHON_BIN || "python3";
+const args = process.argv.slice(2);
+
+const venvDir = path.join(os.homedir(), ".buzzjam-venv");
+const venvPython = process.platform === "win32" 
+  ? path.join(venvDir, "Scripts", "python.exe") 
+  : path.join(venvDir, "bin", "python");
+
+function run(command, commandArgs, options = {}) {
+  return spawnSync(command, commandArgs, {
+    stdio: "inherit",
+    ...options,
+  });
+}
+
+function runCapture(command, commandArgs) {
+  return spawnSync(command, commandArgs, {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+  });
+}
+
+function ensurePython() {
+  const check = runCapture(pythonBin, ["--version"]);
+  if (check.status !== 0) {
+    console.error(`Buzzjam requires ${pythonBin}. Please install Python 3 on your system first.`);
+    process.exit(check.status || 1);
+  }
+}
+
+function ensureVenvAndPackage() {
+  if (!fs.existsSync(venvDir)) {
+    console.log("\n📦 Setting up Buzzjam isolated Python environment (this may take a minute)...");
+    const venv = run(pythonBin, ["-m", "venv", venvDir]);
+    if (venv.status !== 0) {
+      console.error("❌ Failed to create virtual environment.");
+      process.exit(venv.status || 1);
+    }
+  }
+
+  const probe = runCapture(venvPython, ["-m", "pip", "show", "buzzjam"]);
+  if (probe.status === 0) return;
+
+  console.log("⬇️  Installing Buzzjam Python dependencies...\n");
+  const install = run(venvPython, ["-m", "pip", "install", "--upgrade", repoSpec]);
+  if (install.status !== 0) {
+    console.error("\n❌ Failed to install Buzzjam Python package.");
+    process.exit(install.status || 1);
+  }
+  console.log("\n✅ Buzzjam installed successfully!\n");
+}
+
+function runBuzzjam() {
+  const result = run(venvPython, ["-m", "buzzjam", ...args]);
+  process.exit(result.status || 0);
+}
+
+ensurePython();
+ensureVenvAndPackage();
+runBuzzjam();

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@nikanjuri/buzzjam-cli",
+  "version": "3.0.0",
+  "description": "Global npm wrapper for the Buzzjam Python CLI",
+  "license": "MIT",
+  "bin": {
+    "buzzjam": "bin/buzzjam.js"
+  },
+  "files": [
+    "bin"
+  ],
+  "keywords": [
+    "buzzjam",
+    "lyrics",
+    "karaoke",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nikanjuri/buzzjam.git"
+  },
+  "homepage": "https://github.com/nikanjuri/buzzjam",
+  "bugs": {
+    "url": "https://github.com/nikanjuri/buzzjam/issues"
+  }
+}