freepassport-c/README.md

# FreePassport-C Media Player

FreePassport-C Media Player is a low-dependency SDL2 + FFmpeg application inspired by the interactive program guides used on older Cisco and Scientific Atlanta Explorer cable boxes. It turns a local media library into a fullscreen-first virtual cable system with live-seeking channels, a retro guide, and broadcast-style on-screen overlays.

## Features

- Live-TV epoch clock based on `time(NULL)`
- 200 ms black-screen channel tuning delay
- Fullscreen and guide modes
- 5-row Passport-style guide with a 90-minute timeline
- Background decoder thread with a bounded frame queue
- Automatic channel discovery from `./media`
- Randomized per-channel schedules on each launch
- Fullscreen channel banner, theme picker, and about panel

## Layout

- `src/` - application, UI, channel scan, and playback code
- `media/` - channel video files
- `guide-ui.jpg` - visual reference used for proportions and palette

## Controls

- `Up` / `Down` - surf channels
- `Tab` - toggle guide
- `Enter` - tune selected channel from the guide
- `Left` / `Right` - browse guide time
- `0-9` - direct channel number entry
- `i` - show current channel info
- `a` - toggle about panel
- `b` - toggle theme picker
- `f` - toggle fullscreen
- `Esc` - exit guide or quit the app

## Build

Install development packages for SDL2, SDL2_ttf, SDL2_image, and FFmpeg headers before building.

Typical Debian or Ubuntu packages:

```bash
sudo apt install build-essential libsdl2-dev libsdl2-ttf-dev libsdl2-image-dev libavformat-dev libavcodec-dev libswscale-dev libswresample-dev libavutil-dev
```

Then build and run:

```bash
make
./passport-c-media-player
```

## AppImage Build

To create a portable AppImage with the included packaging script:

```bash
make appimage
```

The AppImages for `0.1` are built on Debian 13 using `linuxdeploy` and the repository's included scripts. The build automatically detects your architecture and produces the appropriate AppImage:

- **x86_64**: `FreePassport-C-Media-Player-0.1-x86_64.AppImage`
- **ARM64/aarch64**: `FreePassport-C-Media-Player-0.1-aarch64.AppImage`

Users can run it directly:

```bash
./FreePassport-C-Media-Player-0.1-x86_64.AppImage
# or on ARM devices:
./FreePassport-C-Media-Player-0.1-aarch64.AppImage
```

For a fully portable setup, create a `media/` directory in the same folder as the AppImage and add your channel videos there. The AppImage will automatically detect and load channels from this directory.

## Media

The player scans `./media` for channel directories. Each subdirectory is treated as one channel, and the supported video files inside it are shuffled into a randomized schedule for that channel on each launch.

Optional metadata can be provided with `description.txt` inside each channel directory:

```txt
name=Reading
number=56
description=Books, documentaries, and reading-focused programming.
```

Example layout:

```txt
media/
  reading/
    description.txt
    01-intro.mp4
    02-feature.mp4
  computers/
    description.txt
    01-chronicles.mp4
    02-demo.mp4
```

## Fonts

The UI tries `BigBlueTermPlus Nerd Font` first, then falls back to common Linux monospace fonts.