{"id":24842899,"url":"https://github.com/sun-lab-nbb/ataraxis-video-system","last_synced_at":"2026-02-16T13:03:49.587Z","repository":{"id":274751029,"uuid":"807221725","full_name":"Sun-Lab-NBB/ataraxis-video-system","owner":"Sun-Lab-NBB","description":"A Python library that interfaces with a wide range of cameras to flexibly record visual stream data as video files.","archived":false,"fork":false,"pushed_at":"2026-01-13T17:21:13.000Z","size":2564,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T19:21:26.277Z","etag":null,"topics":["camera-interface","ffmpeg","gentl","harvesters","opencv","video-recording"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sun-Lab-NBB.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-05-28T17:28:30.000Z","updated_at":"2026-01-13T17:18:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"a753e0fb-d40f-42d3-9bf0-963ea6ed3aa5","html_url":"https://github.com/Sun-Lab-NBB/ataraxis-video-system","commit_stats":null,"previous_names":["sun-lab-nbb/ataraxis-video-system"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Sun-Lab-NBB/ataraxis-video-system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sun-Lab-NBB%2Fataraxis-video-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sun-Lab-NBB%2Fataraxis-video-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sun-Lab-NBB%2Fataraxis-video-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sun-Lab-NBB%2Fataraxis-video-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sun-Lab-NBB","download_url":"https://codeload.github.com/Sun-Lab-NBB/ataraxis-video-system/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sun-Lab-NBB%2Fataraxis-video-system/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29508740,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T09:05:14.864Z","status":"ssl_error","status_checked_at":"2026-02-16T08:55:59.364Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["camera-interface","ffmpeg","gentl","harvesters","opencv","video-recording"],"created_at":"2025-01-31T08:19:41.672Z","updated_at":"2026-02-16T13:03:49.581Z","avatar_url":"https://github.com/Sun-Lab-NBB.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ataraxis-video-system\n\nA Python library that interfaces with a wide range of cameras to flexibly record visual stream data as video files.\n\n![PyPI - Version](https://img.shields.io/pypi/v/ataraxis-video-system)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ataraxis-video-system)\n[![uv](https://tinyurl.com/uvbadge)](https://github.com/astral-sh/uv)\n[![Ruff](https://tinyurl.com/ruffbadge)](https://github.com/astral-sh/ruff)\n![type-checked: mypy](https://img.shields.io/badge/type--checked-mypy-blue?style=flat-square\u0026logo=python)\n![PyPI - License](https://img.shields.io/pypi/l/ataraxis-video-system)\n![PyPI - Status](https://img.shields.io/pypi/status/ataraxis-video-system)\n![PyPI - Wheel](https://img.shields.io/pypi/wheel/ataraxis-video-system)\n\n___\n\n## Detailed Description\n\nThis library abstracts all necessary steps for acquiring and saving video data. During each runtime, it interfaces with \none or more cameras to grab the raw frames and encodes them as video files stored in the non-volatile memory. The \nlibrary is specifically designed for working with multiple cameras at the same time and supports fine-tuning the \nacquisition and saving parameters to precisely balance the resultant video quality and real-time throughput for \na wide range of applications.\n\n___\n\n## Features\n\n- Supports Windows, Linux, and macOS.\n- Uses OpenCV or GeniCam (Harvesters) to interface with a wide range of consumer, industrial, and scientific cameras.\n- Uses FFMPEG to efficiently encode acquired data as videos in real time using CPU or GPU.\n- Highly customizable and can be extensively fine-tuned for quality or throughput.\n- Includes an MCP server for AI agent integration (compatible with Claude Desktop and other MCP clients).\n- GPL 3 License.\n\n___\n\n## Table of Contents\n\n- [Dependencies](#dependencies)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [MCP Server](#mcp-server-agentic-integration)\n- [API Documentation](#api-documentation)\n- [Developers](#developers)\n- [Versioning](#versioning)\n- [Authors](#authors)\n- [License](#license)\n- [Acknowledgements](#Acknowledgments)\n\n___\n\n## Dependencies\n\n- [FFMPEG](https://www.ffmpeg.org/download.html) version **n8.0**. The installed FFMPEG must be available on the \n  system’s path and callable from Python processes.\n- A [GenTL Producer](https://www.emva.org/wp-content/uploads/GenICam_GenTL_1_6.pdf) interface compatible with the \n  [Harvesters](https://github.com/genicam/harvesters/blob/master/docs/INSTALL.rst#installing-a-gentl-producer) library \n  if the target camera requires the 'harvesters' camera interface. It is recommended to use the CTI interface supplied \n  by the camera’s vendor, if possible, as this typically ensures that the camera performs as advertised. If the \n  camera-specific CTI file is not available, it is possible to instead use a general interface, such as \n  [MvImpactAcquire](https://assets-2.balluff.com/mvIMPACT_Acquire/). This library has been tested using MvImpactAcquire \n  version **2.9.2**.\n\nFor users, all other library dependencies are installed automatically by all supported installation methods \n(see the [Installation](#installation) section).\n\n***Note!*** Developers should see the [Developers](#developers) section for information on installing additional \ndevelopment dependencies.\n\n___\n\n## Installation\n\n### Source\n\nNote, installation from source is ***highly discouraged*** for anyone who is not an active project developer.\n\n1. Download this repository to the local machine using the preferred method, such as git-cloning. Use one of the \n   [stable releases](https://github.com/Sun-Lab-NBB/ataraxis-video-system/tags) that include precompiled binary and \n   source code distribution (sdist) wheels.\n2. If the downloaded distribution is stored as a compressed archive, unpack it using the appropriate decompression tool.\n3. ```cd``` to the root directory of the prepared project distribution.\n4. Run ```python -m pip install .``` to install the project. Alternatively, if using a distribution with precompiled\n   binaries, use ```python -m pip install WHEEL_PATH```, replacing 'WHEEL_PATH' with the path to the wheel file.\n\n### pip\n\nUse the following command to install the library using pip: ```pip install ataraxis-video-system```\n\n___\n\n## Usage\n\n### OS Support Status\n\nWhile this library works on all major operating systems, it is largely up to the maintainers of the low-level library \ncomponents (OpenCV, Harvesters, FFMPEG) to ensure that the operation is smooth on each supported OS. That, in turn, is \nnot always possible for many nuanced reasons. This section summarizes the current state of the library for the three \nexplicitly supported operating systems: macOS, Windows, and Linux.\n\n#### Linux\nThis library was primarily written on and for Linux systems. It is extensively tested on Linux and performs well under\nall test conditions. It is very likely that Linux users will not experience any issues specific to this library.\n\n#### Windows\nThe library is mostly stable on Windows systems, but requires additional setup to ensure smooth operation. First, the \nFFMPEG **has** to be updated to the latest stable version, as older versions may have a drastically reduced encoding \nspeed even with hardware acceleration. Additionally, some of the advanced OpenCV’s features, such as the MSMF HW \ntransformations, have to be disabled to support smooth runtimes on the Windows platform. Typically, the information of \nwhich features to disable is readily available from the OpenCV’s Windows community.\n\n#### macOS\nmacOS mostly works as expected except for live frame displaying, which does not work for modern macOS devices. The issue\nis due to the OS restriction on drawing certain GUI elements outside the main thread of the application. The restriction\ninterferes with the library, as it displays the acquired frames from the same process that interfaces with the camera \nto minimize the visual lag between grabbing and displaying the frame. This is a persistent issue that is unlikely to \nbe fixed any time soon.\n\n### Quickstart\nThis is a minimal example of how to use this library. It is also available as a [script](examples/quickstart.py).\nThis example is intentionally kept minimal, consult the\n[API documentation](https://ataraxis-video-system-api-docs.netlify.app/) for all available VideoSystem configuration \nparameters.\n\nMost library functionality is accessible through the **VideoSystem** class:\n```\nfrom pathlib import Path\n\nimport numpy as np\nimport tempfile\nfrom ataraxis_time import PrecisionTimer\nfrom ataraxis_data_structures import DataLogger, assemble_log_archives\nfrom ataraxis_base_utilities import console, LogLevel\n\nfrom ataraxis_video_system import VideoSystem, VideoEncoders, CameraInterfaces, extract_logged_camera_timestamps\n\n# Since the VideoSystem and DataLogger classes use multiprocessing under-the-hood, the runtime must be protected by the\n# __main__ guard.\nif __name__ == \"__main__\":\n\n    # Enables the console module to communicate the example's runtime progress via the terminal.\n    console.enable()\n\n    # Specifies the directory where to save the acquired video frames and timestamps.\n    tempdir = tempfile.TemporaryDirectory()  # Creates a temporary directory for illustration purposes\n    output_directory = Path(tempdir.name)\n\n    # The DataLogger is used to save frame acquisition timestamps to disk as uncompressed .npy files.\n    logger = DataLogger(output_directory=output_directory, instance_name=\"webcam\")\n\n    # The DataLogger has to be started before it can save any log entries.\n    logger.start()\n\n    # The VideoSystem minimally requires an ID and a DataLogger instance. The ID is critical, as it is used to identify\n    # the log entries generated by the VideoSystem. For VideoSystems that will be saving frames, output_directory is\n    # also required\n    vs = VideoSystem(\n        system_id=np.uint8(101),\n        data_logger=logger,\n        output_directory=output_directory,\n        camera_interface=CameraInterfaces.OPENCV,  # OpenCV interface for webcameras\n        display_frame_rate=15,  # Displays the acquired data at a rete of 15 frames per second\n        color=False,  # Acquires images in MONOCHROME mode\n        video_encoder=VideoEncoders.H264,  # Uses H264 CPU video encoder.\n        quantization_parameter=25,  # Increments the default qp parameter to reflect using the H264 encoder.\n    )\n\n    # Calling this method arms the video system and starts frame acquisition. However, the frames are not initially\n    # saved to disk.\n    vs.start()\n    console.echo(f\"VideoSystem: Started\", level=LogLevel.SUCCESS)\n\n    console.echo(f\"Acquiring frames without saving...\")\n    timer = PrecisionTimer(\"s\")\n    timer.delay(delay=5, block=False)  # During this delay, camera frames are displayed to the user but are not saved\n\n    # Begins saving frames to disk as an MP4 video file\n    console.echo(f\"Saving the acquired frames to disk...\")\n    vs.start_frame_saving()\n    timer.delay(delay=5, block=False)  # Records frames for 5 seconds, generating ~150 frames\n    vs.stop_frame_saving()\n\n    # Frame acquisition can be started and stopped as needed, although all frames are written to the same output\n    # video file.\n\n    # Stops the VideoSystem runtime and releases all resources\n    vs.stop()\n    console.echo(f\"VideoSystem: Stopped\", level=LogLevel.SUCCESS)\n\n    # Stops the DataLogger and assembles all logged data into a single .npz archive file. This step is required to be\n    # able to extract the timestamps for further analysis.\n    logger.stop()\n    console.echo(f\"Assembling the frame timestamp log archive...\")\n    assemble_log_archives(remove_sources=True, log_directory=logger.output_directory, verbose=True)\n\n    # Extracts the list of frame timestamps from the assembled log archive generated above. This returns a list of\n    # timestamps. Each is given in microseconds elapsed since the UTC epoch onset.\n    console.echo(f\"Extracting frame acquisition timestamps from the assembled log archive...\")\n    timestamps = extract_logged_camera_timestamps(log_path=logger.output_directory.joinpath(f\"101_log.npz\"))\n\n    # Computes and prints the frame rate of the camera based on the extracted frame timestamp data.\n    timestamp_array = np.array(timestamps, dtype=np.uint64)\n    time_diffs = np.diff(timestamp_array)\n    fps = 1 / (np.mean(time_diffs) / 1e6)\n    console.echo(\n        message=(\n            f\"According to the extracted timestamps, the interfaced camera had an acquisition frame rate of \"\n            f\"approximately {fps:.2f} frames / second.\"\n        ),\n        level=LogLevel.SUCCESS,\n    )\n\n    # Cleans up the temporary directory before shutting the runtime down.\n    tempdir.cleanup()\n```\n\n### Data Logging\nThis library relies on the [DataLogger](https://github.com/Sun-Lab-NBB/ataraxis-data-structures#datalogger) class to \nsave frame acquisition timestamps to disk during runtime. Each **saved** frame’s acquisition timestamp is serialized \nand saved as an uncompressed **.npy** file.\n\nThe same DataLogger instance as used by the VideoSystem instances may be shared by multiple other Ataraxis assets that \ngenerate log entries, such as \n[MicroControllerInterface](https://github.com/Sun-Lab-NBB/ataraxis-communication-interface) instances. To support using \nthe same logger instance for multiple concurrently active sources, **each source has to use a unique identifier value\n(system id) when sending data to the logger instance**.\n\n#### Log Format\nEach frame’s acquisition timestamp is logged as a one-dimensional numpy uint8 array, saved as an .npy file. Inside the \narray, the data is organized in the following order:\n1. The uint8 id of the data source (video system instance). The ID occupies the first byte of each log entry.\n2. The uint64 timestamp that specifies the number of microseconds elapsed since the acquisition of the **onset** \n   timestamp (see below). The timestamp occupies **8** bytes following the ID byte. This value communicates when each \n   saved camera frame has been acquired.\n\n**Note!** Timestamps are generated at frame acquisition but are only submitted to the logger when the corresponding \nframe is saved to disk. Therefore, the timestamps always match the order that the saved frames appear in the video file.\n\n#### Onset Timestamp\nEach VideoSystem generates an `onset` timestamp as part of its `start()` method runtime. This log entry uses a modified \ndata order and stores the current UTC time, accurate to microseconds, as the total number of microseconds elapsed since\nthe UTC epoch onset. All further log entries for the same source use the timestamp section of their payloads to \ncommunicate the number of microseconds elapsed since the onset timestamp acquisition. \n\nThe onset log entry uses the following data organization order:\n1. The uint8 id of the data source (video system instance).\n2. The uint64 value **0** that occupies 8 bytes following the source id. A 'timestamp' value of 0 universally indicates \n   that the log entry stores the onset timestamp.\n3. The uint64 value that stores the number of microseconds elapsed since the UTC epoch onset. This value specifies the \n   current time when the onset timestamp was generated.\n\n#### Working with VideoSystem Logs\nSee the [quickstart](#quickstart) example above for a demonstration on how to assemble and parse the frame acquisition\nlog archives generated by the VideoSystem instance at runtime. \n\n**Note!** The parsed frame acquisition timestamps are returned as a tuple of values that match the order in which the \nframes were saved to disk as an .mp4 file. Each timestamp is given as the number of microseconds elapsed since the UTC \nepoch onset.\n\n### CLI\n\nThis library exposes the `axvs` Command-Line Interface (CLI) as part of its installation into a Python environment. To\nsee the list of available CLI commands, call the `axvs --help` command from the environment that has the library\ninstalled or see the API documentation below.\n\n### MCP Server (Agentic Integration)\n\nThis library includes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI agents\nto programmatically interact with camera discovery, configuration, and video recording functionality. The MCP server\nexposes the following tools:\n\n**Camera Discovery and Configuration:**\n- **list_cameras**: Discovers all cameras compatible with OpenCV and Harvesters interfaces.\n- **get_cti_status**: Checks whether the library is configured with a valid GenTL Producer (.cti) file.\n- **set_cti_file**: Configures the library to use a specified CTI file for GeniCam camera support.\n\n**Runtime Requirements:**\n- **check_runtime_requirements**: Checks FFMPEG and GPU availability for video encoding.\n\n**Video Session Management:**\n- **start_video_session**: Starts a video capture session with specified camera and encoding parameters.\n- **stop_video_session**: Stops the active video capture session and releases resources.\n- **start_frame_saving**: Begins saving captured frames to a video file.\n- **stop_frame_saving**: Stops saving frames while keeping the session active.\n- **get_session_status**: Returns the current status of the video session.\n\nTo start the MCP server, use the `axvs mcp` command. For integration with Claude Desktop, add the following to the\nClaude Desktop configuration file (`~/.config/claude/claude_desktop_config.json` on Linux,\n`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or\n`%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"ataraxis-video-system\": {\n      \"command\": \"axvs\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n### Using GeniCam Compatible Cameras\nThis library supports all cameras compatible with the [GeniCam](https://www.emva.org/standards-technology/genicam/) \nstandard, which includes most GigE+ scientific and machine vision cameras. \n\n**Note!** Before using the library with a GeniCam camera, it must be provided with the path to the .cti GenTL Producer\nInterface file. Without an interface, the library is not able to interface with the GeniCam cameras. Use the \n`axvs cti` CLI command to configure the library to use the .cti file provided by the camera vendor (preferred) or a \ngeneral .cti file, such as [mvImpactAcquire](#dependencies). This command only needs to be called once, as the library \nremembers and reuses the provided .cti file for all future runtimes.\n\n___\n\n## API Documentation\n\nSee the [API documentation](https://ataraxis-video-system-api-docs.netlify.app/) for the\ndetailed description of the methods and classes exposed by components of this library.\n\n**Note!** The API documentation also includes the details about the `axvs` CLI interface exposed by this library.\n\n___\n\n## Developers\n\nThis section provides installation, dependency, and build-system instructions for project developers.\n\n### Installing the Project\n\n***Note!*** This installation method requires **mamba version 2.3.2 or above**. Currently, all Sun lab automation \npipelines require that mamba is installed through the [miniforge3](https://github.com/conda-forge/miniforge) installer.\n\n1. Download this repository to the local machine using the preferred method, such as git-cloning.\n2. If the downloaded distribution is stored as a compressed archive, unpack it using the appropriate decompression tool.\n3. ```cd``` to the root directory of the prepared project distribution.\n4. Install the core Sun lab development dependencies into the ***base*** mamba environment via the \n   ```mamba install tox uv tox-uv``` command.\n5. Use the ```tox -e create``` command to create the project-specific development environment followed by \n   ```tox -e install``` command to install the project into that environment as a library.\n\n### Additional Dependencies\n\nIn addition to installing the project and all user dependencies, install the following dependencies:\n\n1. [Python](https://www.python.org/downloads/) distributions, one for each version supported by the developed project. \n   Currently, this library supports the three latest stable versions. It is recommended to use a tool like \n   [pyenv](https://github.com/pyenv/pyenv) to install and manage the required versions.\n\n### Development Automation\n\nThis project comes with a fully configured set of automation pipelines implemented using \n[tox](https://tox.wiki/en/latest/user_guide.html). Check the [tox.ini file](tox.ini) for details about the \navailable pipelines and their implementation. Alternatively, call ```tox list``` from the root directory of the project\nto see the list of available tasks.\n\n**Note!** All pull requests for this project have to successfully complete the ```tox``` task before being merged. \nTo expedite the task’s runtime, use the ```tox --parallel``` command to run some tasks in-parallel.\n\n### Automation Troubleshooting\n\nMany packages used in 'tox' automation pipelines (uv, mypy, ruff) and 'tox' itself may experience runtime failures. In \nmost cases, this is related to their caching behavior. If an unintelligible error is encountered with \nany of the automation components, deleting the corresponding .cache (.tox, .ruff_cache, .mypy_cache, etc.) manually \nor via a CLI command typically solves the issue.\n\n___\n\n## Versioning\n\nThis project uses [semantic versioning](https://semver.org/). See the \n[tags on this repository](https://github.com/Sun-Lab-NBB/ataraxis-video-system/tags) for the available project \nreleases.\n\n___\n\n## Authors\n\n- Ivan Kondratyev ([Inkaros](https://github.com/Inkaros))\n- Jacob Groner ([Jgroner11](https://github.com/Jgroner11))\n- Natalie Yeung\n\n___\n\n## License\n\nThis project is licensed under the GPL3 License: see the [LICENSE](LICENSE) file for details.\n\n___\n\n## Acknowledgments\n\n- All Sun lab [members](https://neuroai.github.io/sunlab/people) for providing the inspiration and comments during the\n  development of this library.\n- The creators of all other dependencies and projects listed in the [pyproject.toml](pyproject.toml) file.\n\n___\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsun-lab-nbb%2Fataraxis-video-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsun-lab-nbb%2Fataraxis-video-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsun-lab-nbb%2Fataraxis-video-system/lists"}