Metadata-Version: 2.4
Name: avialsync
Version: 0.1.0b9
Summary: GUI desktop app to scrub time-synchronized multi-camera video and dense time series.
Project-URL: Homepage, https://github.com/anzalks/avialsync
Project-URL: Documentation, https://avialsync.readthedocs.io/
Project-URL: Source, https://github.com/anzalks/avialsync
Project-URL: Issues, https://github.com/anzalks/avialsync/issues
Project-URL: Changelog, https://github.com/anzalks/avialsync/releases
Author-email: Anzal K Shahul <anzal.ks@gmail.com>
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: behaviour,electrophysiology,multi-camera,neuroscience,pose-estimation,synchronization,time-series,video
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video :: Display
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: <3.13,>=3.11
Requires-Dist: av>=12
Requires-Dist: neo
Requires-Dist: numpy
Requires-Dist: polars
Requires-Dist: pyqtgraph
Requires-Dist: pyside6
Requires-Dist: quantities>=0.16.3
Requires-Dist: tzdata; sys_platform == 'win32'
Requires-Dist: xxhash
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: hypothesis; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pillow; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-benchmark; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-qt; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pyyaml; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.1; extra == 'docs'
Requires-Dist: myst-parser>=2.0; extra == 'docs'
Requires-Dist: sphinx>=7.2; extra == 'docs'
Description-Content-Type: text/markdown

# AvialSync

**The Advanced Video and Instrument Alignment Library.**

[![PyPI](https://img.shields.io/pypi/v/avialsync.svg)](https://pypi.org/project/avialsync/)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://pypi.org/project/avialsync/)
[![CI](https://github.com/anzalks/avialsync/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/anzalks/avialsync/actions/workflows/ci.yml)
[![Documentation](https://readthedocs.org/projects/avialsync/badge/?version=latest)](https://avialsync.readthedocs.io/en/latest/)
[![Licence](https://img.shields.io/badge/licence-AGPL--3.0-blue.svg)](https://github.com/anzalks/avialsync/blob/main/LICENSE)
[![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/anzalks/avialsync/releases)

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 exists for the case where **the video and the signal have to agree on the same instant**, and the
recordings came off independently-clocked hardware. It is built for visual inspection and careful
alignment: it does not acquire recordings, it does not analyse them for you, and it never silently
changes a scientific timestamp. Your lab can add support for its own file types and workflows
through plugins.

![A one-second loop of three synchronised camera views of a head-fixed mouse with 2D pose overlays,
a 3D pose view, and the wheel encoder velocity trace advancing together on one master
timeline.](https://raw.githubusercontent.com/anzalks/avialsync/main/docs/_static/screenshots/aol_session_overview.gif)

*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](https://avialsync.readthedocs.io/en/latest/plugin-guide.html)
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](https://github.com/anzalks/avialsync/releases): `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](https://avialsync.readthedocs.io/en/latest/install.html#first-launch-security-warnings).

**PyPI**, on Python 3.11 or 3.12:

```bash
python -m pip install avialsync
avialsync
```

That is the whole install. Video decoding, proxy generation, and clip export all run inside the
Python packages, so there is no media runtime to install separately and nothing to configure.

One caveat, and it is Qt's rather than AvialSync's: **on Linux**, PySide6 needs the usual desktop
graphics libraries (`libgl1`, `libxkbcommon`, and the xcb set). Every normal desktop already has
them; bare containers and minimal server images do not. No packaging choice removes it.

Apple silicon is required for the `.dmg`, and glibc 2.39+ for the AppImage; outside those, use pip.
See [Installation](https://avialsync.readthedocs.io/en/latest/install.html) for details.

## First session

```bash
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](https://avialsync.readthedocs.io/en/latest/)**
— [quickstart](https://avialsync.readthedocs.io/en/latest/quickstart.html),
[first-session tutorial](https://avialsync.readthedocs.io/en/latest/tutorials/first-session.html),
[supported formats](https://avialsync.readthedocs.io/en/latest/formats.html),
[synchronization](https://avialsync.readthedocs.io/en/latest/tutorials/synchronization.html),
[troubleshooting](https://avialsync.readthedocs.io/en/latest/troubleshooting.html),
[plugin guide](https://avialsync.readthedocs.io/en/latest/plugin-guide.html), and a
[technical reference](https://avialsync.readthedocs.io/en/latest/technical/index.html) covering
architecture, data handling, performance, and the development and release process.

## Contributing

Contributions are welcome — see
[CONTRIBUTING.md](https://github.com/anzalks/avialsync/blob/main/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](https://github.com/anzalks/avialsync/blob/main/CODE_OF_CONDUCT.md).

Good places to start are format plugins (the `TimeSeriesSource` / `VideoSource` contracts are frozen
— see the [plugin guide](https://avialsync.readthedocs.io/en/latest/plugin-guide.html)), platform
verification on real hardware, and the open items under "Pending" in `HANDOUT.md`.

## Licence

AvialSync is free software under the
[GNU AGPL v3 or later](https://github.com/anzalks/avialsync/blob/main/LICENSE). 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.

There is no dual licence and no contributor agreement — contributions are accepted under the same
AGPL, and opening a pull request is the whole process.
