Document player features and usage

README.md

@@ -1,17 +1,70 @@
 # C41 Recorder Player
 
-Run:
+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.
+
+## Start The Player
+
+From this directory, run:
 
 ```sh
 python3 server.py
 ```
 
-Then open <http://127.0.0.1:8765>. The server indexes the dated folders in
-`/home/human/Videos/Yassine Salon/C41/media` and uses FFmpeg to convert only the
-currently playing AVI clip for the browser. Original recordings are unchanged.
+Open <http://127.0.0.1:8765> in a browser.
 
-To use another archive or port:
+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.
+
+## Custom Folders And Ports
+
+To use a different output folder or port:
 
 ```sh
-python3 server.py "/path/to/media" --port 9000
+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`.