recorder-player/README.md

C41 Recorder Player

A small local web player for the C41 recorder archive. It turns the recorder's dated video folders into a simple daily view that is easy to search and play.

Features

• Shows recordings on a full 24-hour timeline.
• Uses the time in each filename to place clips at the correct time of day.
• Shows recorded minutes in light blue and empty periods in dark blue.
• Lets you choose the recording date.
• Plays browser-friendly MP4 files immediately.
• Converts an AVI clip automatically when no MP4 copy exists.
• Provides a YouTube-style play/pause button and progress bar.
• Provides volume control and mute.
• Jumps backward or forward by 10 seconds.
• Crosses clip boundaries and skips empty periods during 10-second jumps.
• Zooms the timeline to inspect a smaller time range.
• Supports keyboard shortcuts.
• Can manually encode the archive from the Encoding menu.
• Shows encoding progress, completed files, skipped files, and errors.
• Never overwrites an existing transcoded file.
• Keeps all original AVI recordings unchanged.
• Saves named highlight periods for later review or automated processing.

Start The Player

From this directory, run:

python3 server.py

Open http://127.0.0.1:8765 in a browser.

Docker

Docker keeps the application and FFmpeg inside a container while the recorder files remain on the host. From this directory, run:

docker compose up -d --build

Open http://127.0.0.1:8765. The Compose configuration mounts the original archive read-only at /data/source and stores encoded files persistently in /data/encoded. Stop it with:

docker compose down

To use different host folders, edit the two volumes entries in compose.yaml. Do not remove :ro from the source mount.

The default source archive is:

/home/human/Videos/Yassine Salon/C41/media

The default browser-friendly output archive is:

/home/human/Videos/Yassine Salon/C41/media-mp4

Keyboard Shortcuts

• Space: play or pause.
• Left arrow: go back 10 seconds.
• Right arrow: go forward 10 seconds.
• M: mute or unmute.

Encoding

Open Encoding in the player and press Start. The encoder creates small, browser-compatible H.264/AAC MP4 files in media-mp4, preserving the dated folder structure.

Encoding can take time because the original files use HEVC video. You can keep using the player while encoding runs. Files that already have an MP4 copy are reported as skipped. A temporary file is used during each conversion, so an interrupted conversion cannot damage an existing file.

Highlights And AI Automation

To create a highlight in the player, play the recording, press Mark start, move to the end of the interesting part, press Mark end, enter a name, and press Add highlight. Highlights are saved in media-mp4/highlights.json.

The highlight API is intentionally simple. An AI agent can list highlights:

curl http://127.0.0.1:8765/api/highlights

It can append one using normal date and clock values:

curl -X POST http://127.0.0.1:8765/api/highlights \
  -H 'Content-Type: application/json' \
  -d '{"date":"2026-08-27","start_time":"09:26:40","end_time":"09:28:40","title":"Person at entrance"}'

The API stores the entry without changing any video. start and end may also be used as seconds from midnight, and duration may be used instead of an end time. For example, {"start":"09:26:40","duration":120} creates a two-minute highlight. This makes it straightforward for an AI to append detections, labels, or review segments programmatically.

Custom Folders And Ports

To use a different output folder or port:

python3 server.py "/path/to/output-media" --source "/path/to/source-media" --port 9000

The source and output folders should contain dated folders named like 20260827, with clips named like 09.28.36.avi or 09.28.36.mp4.