skelly_synchronize
Synchronization tool for videos of the same event. Uses audio cross correlation to synchronize.
Science Score: 44.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
✓CITATION.cff file
Found CITATION.cff file -
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
○DOI references
-
○Academic publication links
-
○Committers with academic emails
-
○Institutional organization owner
-
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (13.0%) to scientific vocabulary
Keywords
Repository
Synchronization tool for videos of the same event. Uses audio cross correlation to synchronize.
Basic Info
- Host: GitHub
- Owner: freemocap
- License: agpl-3.0
- Language: Python
- Default Branch: main
- Homepage: https://freemocap.github.io/skelly_synchronize/
- Size: 837 KB
Statistics
- Stars: 17
- Watchers: 3
- Forks: 2
- Open Issues: 3
- Releases: 1
Topics
Metadata Files
README.md
Skelly Synchronize
Skelly Synchronize is a package for synchronizing videos post-recording, without the need for timestamps. There are multiple options for synchronizing videos, including cross correlation of the audio files and contrast checking of the video brightness. The videos will be synchronized so that they all start at the earliest shared time, and end at the latest shared time.
Install and Run
Skellysynchronize can be installed through pip by running `pip install skellysynchronizein your terminal. Once it has installed, it can be run with the commandpython -m skelly_synchronize`.
While running, the GUI window may appear frozen, but the terminal should show the progress. Large videos may take a significant amount of time.
Skelly_synchronize currently depends on FFmpeg, a command line tool that handles the video files. If you do not have FFmpeg downloaded, you will need to install it separately. You can download FFmpeg here: https://ffmpeg.org/download.html
Using Skelly Synchronize
Once you have the GUI open, choose a folder of raw videos that you would like to synchronize. The videos must overlap in time to be able to be synchronized. The software currently works with mp4, mkv, avi, mpeg, and mov files. Once the folder of videos has been selected, you can press the button for the synchronization method you would like to run. The synchronized videos will be placed in a folder called "synchronized_videos" that will be in the same directory as the folder of raw videos.
Synchronization Methods
Audio Cross Correlation synchronizes by aligning the audio files of each video as closely as possible. Cross correlation is a mathematical technique used to find the amount of offset between different signals. In this case, Skelly Synchronize is using cross correlation to find the time difference between the audio tracks of the video files.
Brightness Contrast Detection synchronizes by looking for a quick flash near the beginning of each video. This flash can be from a camera flash, turning on a light, or even opening curtains to a bright window. Skelly Synchronize looks for the first time in each video that the change in brightness (contrast) between subsequent frames passes a certain threshold, and then aligns the brightness change of each video. The brightness contrast threshold used can be set as a parameter in the GUI, and higher threshold values will require a more abrupt and brighter flash in the video. Synchronization will be best if all cameras see the flash at the same time, so methods like turning on a light will yield better synchronization than methods like opening curtains.
Video Requirements
For audio synchronization, all videos must have audio tracks. Synchronization will work better if there are short, distinct sounds audible from each camera, for example a loud clap.
For brightness synchronization, there must be a quick increase in brightness across all of the video files. This method requires a significant brightness change visible to all cameras, for example turning on a bright light or firing a flash visible to all cameras. The synchronization will be based off of the first brightness change in each video that crosses a threshold. You can set the brightness ratio threshold in the gui before synchronizing. The threshold takes into account both the brightness contrast compared to the preceding frame, and the rate of change of brightness contrast. It may take multiple tries with different brightness ratio thresholds to get proper synchronization, although the default should work in most cases.
Additional Files
Skelly synchronize will create a variety of additional files during synchronization, depending on what synchronization method is used and what preprocessing steps are required for your videos.
Two debug files will always be created. The first, debug_plot.png, shows a visualization of the videos pre and post synchronization to give visual confirmation of the synchronization process. The second, synchronization_debug.toml, gives information on both the raw and synchronized videos, and provides the lag dictionary, which shows the offsets in seconds between the start of each raw video and the first moment all videos recorded.
Videos that do not have the same framerate (and audio files that do not have the same sample rate) will be normalized to have matching framerates, which will create a "normalized_videos" folder inside of the raw videos folder that has normalized copies of the original videos.
Audio synchronization will place the extracted audio files into the synchronized video folder. Brightness synching will place numpy files containing the brightness of the videos across time in both the raw and synchronized video folders.
Owner
- Name: The FreeMoCap Project
- Login: freemocap
- Kind: organization
- Email: info@freemocap.org
- Location: United States of America
- Website: https://freemocap.org
- Twitter: freemocap
- Repositories: 6
- Profile: https://github.com/freemocap
Free Motion Capture For Everyone
Citation (CITATION.cff)
cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
- family-names: Queen
given-names: Philip
- family-names: Matthis
given-names: Jonathan Samir
orcid: https://orcid.org/my-orcid?orcid=0000-0003-3683-646X
title: "SkellySynchronize"
doi: 10.5281/zenodo.10395651
GitHub Events
Total
- Issues event: 3
- Watch event: 5
- Delete event: 4
- Issue comment event: 3
- Push event: 24
- Pull request review event: 2
- Pull request event: 15
- Fork event: 1
- Create event: 12
Last Year
- Issues event: 3
- Watch event: 5
- Delete event: 4
- Issue comment event: 3
- Push event: 24
- Pull request review event: 2
- Pull request event: 15
- Fork event: 1
- Create event: 12
Committers
Last synced: over 1 year ago
Top Committers
| Name | Commits | |
|---|---|---|
| philipqueen | q****p@g****m | 185 |
| jonmatthis | j****s@g****m | 4 |
Issues and Pull Requests
Last synced: 6 months ago
All Time
- Total issues: 8
- Total pull requests: 46
- Average time to close issues: 17 days
- Average time to close pull requests: 16 days
- Total issue authors: 5
- Total pull request authors: 3
- Average comments per issue: 1.25
- Average comments per pull request: 0.2
- Merged pull requests: 45
- Bot issues: 0
- Bot pull requests: 0
Past Year
- Issues: 3
- Pull requests: 12
- Average time to close issues: 12 days
- Average time to close pull requests: 21 days
- Issue authors: 2
- Pull request authors: 2
- Average comments per issue: 1.33
- Average comments per pull request: 0.17
- Merged pull requests: 11
- Bot issues: 0
- Bot pull requests: 0
Top Authors
Issue Authors
- philipqueen (3)
- miahoffmannd (2)
- rrrcabral (1)
- jonmatthis (1)
- 0ArchLinux0 (1)
Pull Request Authors
- philipqueen (50)
- aaroncherian (2)
- jonmatthis (1)
Top Labels
Issue Labels
Pull Request Labels
Packages
- Total packages: 1
-
Total downloads:
- pypi 1,611 last-month
- Total dependent packages: 0
- Total dependent repositories: 0
- Total versions: 31
- Total maintainers: 1
pypi.org: skelly-synchronize
Basic template of a python repository
- Homepage: https://freemocap.org
- Documentation: https://freemocap.github.io/skelly_synchronize/
- License: GNU Affero General Public License v3 or later (AGPLv3+)
-
Latest release: 2025.4.1037
published 10 months ago
Rankings
Maintainers (1)
Dependencies
- actions/checkout v3 composite
- psf/black stable composite
- actions/checkout v3 composite
- actions/setup-python v3 composite
- pypa/gh-action-pypi-publish 27b31702a0e7fc50959f5ad993c78deac1bdfc29 composite
- actions/checkout v3 composite
- actions/setup-python v4 composite
- actions/upload-artifact v3 composite
- PyQt6 *
- deffcode *
- librosa *
- matplotlib *
- numpy *
- opencv-contrib-python *
- pytest *
- scipy *
- setuptools *
- toml *