bckplayer 0.1.0

A cross-platform CLI media player interface for VLC
Documentation

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)

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