bckplayer 0.1.0

# 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](https://www.videolan.org/vlc/)
     - 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](https://github.com/yt-dlp/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](https://rustup.rs/)

## Installation


### From Source


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


```bash
# 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](YOUTUBE.md) for detailed information.

### Quick YouTube Usage


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


```json
{
  "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:

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


```bash
# 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](https://ffmpeg.org/) - The excellent multimedia framework including ffplay
- [ratatui](https://github.com/ratatui-org/ratatui) - Terminal UI framework
- [tokio](https://tokio.rs/) - Async runtime
- [rust_ffplay](https://docs.rs/rust_ffplay/) - Rust wrapper for FFplay