AvialSync

The Advanced Video and Instrument Alignment Library.

AvialSync is a desktop viewer for looking through an experiment in time.

Use it when you have video from one or more cameras together with recordings such as sensors, electrodes, behavioural tracking, or other time-stamped measurements. It places them on one shared timeline so you can move to an event and inspect what each recording shows at that moment.

It is built for visual inspection and careful alignment. It does not acquire recordings and it does not perform analysis for you. Your lab can add support for its own file types and workflows through plugins.

A real recording session: three cameras at 230 fps with per-camera 2D pose drawn over each view, triangulated 3D pose on the right, and wheel-encoder velocity below — one second of it, at the speed it was recorded, every source moving on one master clock. The whole folder was opened by dropping it on the window; a session plugin recognised the layout and placed each file, including the shared time base. Nothing in AvialSync knows this lab's format.

What it gives you

• Several camera recordings playing together on one clock.
• Sensor, electrode, and tracking traces beside the video, up to 50 kHz across many channels.
• Alignment by offset, drift, or TTL/event evidence, with the original files left unchanged.
• Event marks, A/B time ranges, and exports of snapshots or selected spans for analysis elsewhere.

Install

Desktop installer (recommended). Download from the Releases page: AvialSync-Setup.exe on Windows, AvialSync.dmg on macOS, or AvialSync.AppImage on Linux. Everything needed is bundled. The artifacts are not yet code-signed, so the first launch needs one extra click.

PyPI, on Python 3.11 or 3.12:

python -m pip install avialsync
avialsync

The pip caveat. pip installs every Python dependency but cannot install the two native components AvialSync needs for video: libmpv and FFmpeg. They are shared libraries and programs, not Python packages — python-mpv is only a binding to a libmpv that must already exist on the machine. Without them AvialSync still opens and every time-series feature works, but video stays disabled and a Missing libmpv dialog appears. Install them once with brew install ffmpeg mpv, sudo apt install ffmpeg libmpv2, sudo dnf install ffmpeg mpv-libs, or sudo pacman -S ffmpeg mpv. Windows needs a manual libmpv download — full instructions.

Apple silicon is required for the .dmg, and glibc 2.39+ for the AppImage; outside those, use pip. See Installation for details.

First session

avialsync demo

That generates and opens a complete sample session — four cameras, sensor and ephys traces, tracking — so you can try everything before touching your own data. With your own recordings:

1. Drag video and data files onto the window, or use Open Videos and Open Sensor/Ephys Data.
2. Video appears at the top, traces below it.
3. Drag the shared time bar to inspect one moment across every recording.
4. If recordings do not line up, use the synchronization tools to align a visible event or TTL pulse.

A camera with no coverage at the selected time shows No Footage rather than a stale frame, and Data Streams shows when each file has data.

Documentation

Full documentation is at avialsync.readthedocs.io — quickstart, first-session tutorial, supported formats, synchronization, troubleshooting, plugin guide, and a technical reference covering architecture, data handling, performance, and the development and release process.

How it compares

Neighbouring open-source tools, described as their authors position them. They overlap less than the names suggest.

If you mainly plot signals, PlotJuggler is likely a better fit. If you are in a ROS ecosystem, Foxglove and Rerun are built for it. AvialSync exists for the narrower case where the video and the signal have to agree on the same instant, and the recordings came off independently-clocked hardware.

It is not an acquisition system, not a replacement for your analysis pipeline, and it never silently changes scientific timestamps.

Contributing

Contributions are welcome — see CONTRIBUTING.md for setup, the four-command gate every change must pass, and the architecture rules that exist because breaking them caused real bugs. Participation is governed by our Code of Conduct.

Good places to start are format plugins (the TimeSeriesSource / VideoSource contracts are frozen — see the plugin guide), platform verification on real hardware, and the open items under "Pending" in HANDOUT.md.

Contributions are accepted under CLA.md: you keep the copyright in your work and grant the right to ship it under both licences below. One line in your first pull request covers it.

Licence

AvialSync is free software under the GNU AGPL v3 or later. Use it, study it, modify it, redistribute it. The one condition is reciprocity: if you convey a modified version — including letting others use it over a network — you publish your changes under the same licence.

Running it in your lab, modifying it for your own use, publishing results, and writing plugins for your own rig all sit inside this and cost nothing. A plugin that uses only the documented TimeSeriesSource, VideoSource and SessionSource interfaces is your own work and you choose its licence, so a loader for a proprietary instrument format need not be published.

Other arrangements are possible in situations the AGPL cannot accommodate; see licensing in the documentation.