BCK Player

A cross-platform CLI media player interface for VLC with a clean, minimalistic TUI (Text User Interface).

Features

• Cross-platform support: Works on Windows, Linux, and macOS
• VLC integration: Uses VLC media player for reliable media playback with full runtime control
• YouTube support: Direct YouTube URL playback with caching (requires yt-dlp)
• Multiple media sources: Supports local files, URLs, and YouTube videos
• Intelligent caching: YouTube videos are cached locally for faster subsequent playback
• Clean TUI interface: Minimalistic terminal interface with essential controls
• Full playback control: Real-time volume, speed, seeking, and fullscreen control
• Media loading: Simple media file and URL loading
• Keyboard shortcuts: Intuitive keyboard controls for all media functions

Prerequisites

Before using BCK Player, you need to install:

1. VLC Media Player (including development libraries) - The media player engine

   • Windows:
     • Download VLC from videolan.org
     • For development: Download "VLC media player" installer that includes development files
     • Or install via Chocolatey: choco install vlc
     • Ensure VLC is in your system PATH
   • Linux:
     • Ubuntu/Debian: sudo apt install vlc libvlc-dev
     • Arch: sudo pacman -S vlc
     • Fedora: sudo dnf install vlc vlc-devel
   • macOS: brew install --cask vlc

2. yt-dlp (optional, for YouTube support)

   • Windows: Download from yt-dlp releases or pip install yt-dlp
   • Linux: sudo apt install yt-dlp or pip install yt-dlp
   • macOS: brew install yt-dlp or pip install yt-dlp

3. Rust (for building from source)

   • Install from rustup.rs

Installation

From Source

git clone https://github.com/yourusername/bckplayer.git
cd bckplayer
cargo build --release

The binary will be available at target/release/bckplayer (or bckplayer.exe on Windows).

Add to PATH

Copy the binary to a directory in your PATH or add the target/release directory to your PATH.

Usage

Basic Usage

# Launch BCK Player
bckplayer

# Play a local file
bckplayer /path/to/video.mp4

# Play a URL
bckplayer "https://example.com/stream.m3u8"

# Play a YouTube video (requires yt-dlp)
bckplayer "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Start with specific volume and speed
bckplayer --volume 50 --speed 1.5 /path/to/video.mp4

# Start in windowed mode
bckplayer --windowed /path/to/video.mp4

Command Line Options

Usage: bckplayer [OPTIONS] [MEDIA]

Arguments:
  [MEDIA]  Media source to play (file path or URL)

Options:
  -w, --windowed               Start in windowed mode instead of fullscreen
  -v, --volume <VOLUME>        Set initial volume (0-100)
  -m, --muted                  Start muted
  -s, --speed <SPEED>          Set playback speed [default: 1.0]
  -d, --debug                  Enable debug logging
  -h, --help                   Print help
  -V, --version                Print version

Controls

Playback Controls

• Space: Play/Pause
• S: Stop
• ←/→: Seek backward/forward
• +/-: Increase/decrease playback speed
• R: Reset speed to 1.0x

Audio Controls

• ↑/↓: Volume up/down
• M: Mute/unmute

Video Controls

• F: Toggle fullscreen

Interface Controls

• I: Input new media source (file path, URL, or YouTube URL)
• : (colon)**: Enter command mode for advanced operations
  • ytcache: Show YouTube cache statistics
  • ytclear: Clear YouTube cache
  • ytdownload <url>: Download YouTube video without playing
• H: Show/hide help
• C: Show/hide configuration
• Q: Quit application

YouTube Support

BCK Player supports direct YouTube URL playback with intelligent caching. See YOUTUBE.md for detailed information.

Quick YouTube Usage

# Play a YouTube video directly
bckplayer "https://www.youtube.com/watch?v=example"

# Configure YouTube settings
bckplayer  # Press 'c' for config, navigate to YouTube section

Interface

The TUI consists of several sections:

1. Title Bar: Application name and version
2. Media Info: Current file, title, and playback state
3. Controls: Quick reference for keyboard shortcuts
4. Volume: Volume level gauge with mute indicator
5. Progress: Playback position, duration, and speed
6. Status: Current status and input area

VLC Integration

BCK Player uses the VLC media player engine through the vlc-rs crate, providing full runtime control over media playback. Unlike FFplay-based solutions, VLC offers:

• Real-time control: All playback functions work during media playback
• Comprehensive format support: Extensive codec and format compatibility
• Advanced features: Hardware acceleration, subtitle support, and audio effects
• Stable API: Mature and well-documented media player framework

Configuration

BCK Player creates a configuration file at:

• Windows: %APPDATA%\bckplayer\config.json
• Linux: ~/.config/bckplayer/config.json
• macOS: ~/Library/Application Support/bckplayer/config.json

Configuration Options

{
  "default_volume": 100.0,
  "default_speed": 1.0,
  "fullscreen_by_default": false,
  "keybindings": {
    "play_pause": "Space",
    "stop": "s",
    "volume_up": "Up",
    "volume_down": "Down",
    "mute": "m",
    "seek_forward": "Right",
    "seek_backward": "Left",
    "speed_up": "=",
    "speed_down": "-",
    "reset_speed": "r",
    "toggle_fullscreen": "f",
    "quit": "q",
    "help": "h"
  },
  "ui": {
    "update_interval_ms": 100,
    "volume_step": 5.0,
    "seek_step": 10.0,
    "speed_step": 0.1,
    "show_milliseconds": false
  }
}

Supported Media Formats

BCK Player supports all media formats that VLC can handle, including:

• Video: MP4, MKV, AVI, MOV, WebM, FLV, WMV, MPEG, and many more
• Audio: MP3, FLAC, OGG, WAV, AAC, WMA, and many more
• Streaming: HTTP/HTTPS URLs, M3U8 playlists, RTSP, and more
• Subtitles: SRT, ASS, VTT, and embedded subtitles

Troubleshooting

Common Issues

1. "ffplay not found"

   • Ensure FFmpeg is installed and ffplay is available in PATH
   • Use --ffplay-path to specify custom ffplay location

2. Audio/Video playback issues

   • Check FFmpeg installation and codec support
   • Try playing the file directly with ffplay to isolate issues

3. TUI display issues

   • Ensure terminal supports Unicode and colors
   • Try resizing the terminal window
   • Use a different terminal emulator if issues persist

Debug Mode

Enable debug logging with the -d flag:

bckplayer -d /path/to/video.mp4

Platform-Specific Notes

Windows

• Use PowerShell or Command Prompt
• Windows Terminal recommended for best TUI experience

Linux

• Most terminal emulators supported
• X11 and Wayland compatibility

macOS

• Terminal.app and iTerm2 supported
• Requires macOS 10.14+ for best experience

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

Development

# Clone and build
git clone https://github.com/yourusername/bckplayer.git
cd bckplayer
cargo build

# Run tests
cargo test

# Run with debug logging
RUST_LOG=debug cargo run -- --debug

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• FFmpeg - The excellent multimedia framework including ffplay
• ratatui - Terminal UI framework
• tokio - Async runtime
• rust_ffplay - Rust wrapper for FFplay