freepassport-c/README.md

# FreePassport-C Media Player

FreePassport-C Media Player is a low-dependency SDL2 + FFmpeg application that is based on the look of interactive programming guide software used on older Cisco/Scientific Atlanta Explorer cable boxes, it allows you to organize your media into a virtual cable guide with live-seeking channels.

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

## 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
- `i` - show current channel info
- `Esc` - exit guide or quit the app

## Build

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

Typical Debian or Ubuntu packages:

```bash
sudo apt install build-essential libsdl2-dev libsdl2-ttf-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 that can run on any Linux distribution:

```bash
make appimage
```

This creates a self-contained executable that includes all dependencies. The script automatically detects your architecture and produces the appropriate AppImage:

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

Users can run it directly:

```bash
./Passport-C-Media-Player-0.1-x86_64.AppImage
# or on ARM devices:
./Passport-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 played in alphabetical order as that channel's schedule.

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.