Videos

Ethoscopes produce video in two ways: recordings, saved as chunks, and the periodic camera snapshots stored in each results database. Two scripts in the repository turn each into MP4 files.

Converting recorded videos

When an ethoscope records video, it saves it in 10-minute chunks with the extension .h264, which the backup service copies to /ethoscope_data/videos on the node. Most players cannot open these chunks. The script h264_to_mp4.py merges the chunks of each recording into one MP4 file (with ffmpeg, without re-encoding):

python h264_to_mp4.py --path /ethoscope_data/videos

It walks the folder and merges every finished recording whose MP4 is missing or lacks some chunks. A recording counts as finished when the ethoscope has written its recording.info marker, or, for folders without one, when its newest chunk is older than six hours. Options:

Option	Purpose
-p, --path	Root folder of the videos (default /ethoscope_data/videos, or ETHOSCOPE_VIDEOS_DIR)
-l, --list	List the folders that already contain an MP4 file
-e, --extension	Extension of the chunks (default h264)
--fps	Frame rate to use instead of the detected one
--force	Merge again every complete recording, even when its MP4 looks current
--ignore-marker	Convert regardless of the marker and of the chunks’ age, including unfinished recordings
--max-age-hours	Age of the newest chunk after which a folder without a marker is converted (default 6)
--purge	Delete the .h264 chunks that a merged MP4 is known to contain

Run it regularly on the node, for example from cron.

Time-lapse videos from the snapshots

Unless switched off, ethoscopes store a camera snapshot every five minutes in the IMG_SNAPSHOTS table of the results database. The script video_from_ethoscope_db.py turns these snapshots into an MP4 time-lapse, and can draw the tracked position of each fly on it.

It needs the Python packages opencv-python, numpy and tqdm, and ffmpeg with the libx264 encoder. For a simple time-lapse:

python video_from_ethoscope_db.py /path/to/database.db

The video is written next to the database, with the same name and the extension .mp4, for example 2026-03-04_14-52-59_<machine_id>.db gives 2026-03-04_14-52-59_<machine_id>.mp4. It is encoded in H.264 at 30 frames per second and plays in VLC and other common players. Each frame shows its time.

To draw the tracked flies, add --track (or -t):

python video_from_ethoscope_db.py /path/to/database.db --track

Each fly is drawn as an ellipse, as in the live tracking view: centred on its position (x, y), with its length and width (w, h) as axes and rotated by its orientation (phi).

Example time-lapse with tracked flies (MP4, 8 seconds)

How it works

1. It reads the start time of the experiment from the METADATA table.
2. It extracts every JPEG snapshot from IMG_SNAPSHOTS, with its time.
3. With --track, it reads the position of each region of interest from ROI_MAP, loads t, x, y, w, h and phi from each ROI_N table, and converts the positions within each region into image coordinates. For each snapshot, it finds the nearest tracked position of each fly, within 30 seconds.
4. It resizes each frame to 640 × 480, writes the time on it and, optionally, draws the flies.
5. It pipes the frames to ffmpeg, which encodes the MP4.