{"id":13910496,"url":"https://github.com/nomonosound/fast-align-audio","last_synced_at":"2025-04-09T07:06:27.414Z","repository":{"id":178567450,"uuid":"660627730","full_name":"nomonosound/fast-align-audio","owner":"nomonosound","description":"A fast python library for aligning similar audio snippets passed in as NumPy arrays","archived":false,"fork":false,"pushed_at":"2025-03-18T20:38:33.000Z","size":648,"stargazers_count":44,"open_issues_count":3,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T04:59:00.021Z","etag":null,"topics":["audio-alignment"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nomonosound.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2023-06-30T12:47:47.000Z","updated_at":"2025-03-18T20:38:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"c9f0e0b7-0858-4d87-b835-b1bcd7d8b28e","html_url":"https://github.com/nomonosound/fast-align-audio","commit_stats":null,"previous_names":["iver56/fast-align-audio"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomonosound%2Ffast-align-audio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomonosound%2Ffast-align-audio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomonosound%2Ffast-align-audio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nomonosound%2Ffast-align-audio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nomonosound","download_url":"https://codeload.github.com/nomonosound/fast-align-audio/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247994120,"owners_count":21030050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["audio-alignment"],"created_at":"2024-08-07T00:01:29.411Z","updated_at":"2025-04-09T07:06:27.397Z","avatar_url":"https://github.com/nomonosound.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# fast-align-audio: high-speed NumPy audio alignment\n\nfast-align-audio is designed to swiftly align two similar 1-dimensional NumPy arrays — a common need\nin various fields including audio signal processing. If you have two arrays where one\n\"lags behind\" the other due to factors such as different capture sensors (microphones),\npropagation delays, or post-processing like reverberation or MP3 compression,\nfast-align-audio is here to help.\n\nThe package employs a \"brute force\" alignment approach, leveraging a C-based algorithm\nfor maximum speed while providing a user-friendly Python API for easy integration.\n\nWhile this library was initially developed with audio ndarrays in mind, it could also be\nused to align other kinds of time-series data that are represented as 1D NumPy arrays.\n\n# Installation\n\n[![PyPI version](https://img.shields.io/pypi/v/fast-align-audio.svg?style=flat)](https://pypi.org/project/fast-align-audio/)\n![python 3.9, 3.10, 3.11](https://img.shields.io/badge/Python-3.9%20|%203.10%20|%203.11-blue)\n![os: Linux, Windows](https://img.shields.io/badge/OS-Linux%20%28x86%29%20|%20Windows%20%28x86%29-blue)\n\n```\n$ pip install fast-align-audio\n```\n\n# Usage\n\nHere is a basic usage example:\n\n```py\nimport fast_align_audio\nimport numpy as np\n\n# Create a random NumPy array\nreference = np.random.uniform(size=10_000).astype(\"float32\")\ndelayed = np.pad(reference, (121, 0))[0:10_000]\n\n# Find the best offset for aligning two arrays\noffset, mse = fast_align_audio.find_best_alignment_offset(\n    reference_signal=reference,\n    delayed_signal=delayed,\n    max_offset_samples=1000,\n    lookahead_samples=5000,\n)\nprint(offset)  # 121\n\nnegative_offset, mse2 = fast_align_audio.find_best_alignment_offset(\n    reference_signal=reference,\n    delayed_signal=reference[121:],\n    max_offset_samples=1000,\n    lookahead_samples=5000,\n)\nprint(negative_offset)  # -121\n\n# Align two arrays and confirm they're equal post alignment\naligned_audio, gaps = fast_align_audio.align_delayed_signal_with_reference(\n    reference.shape[-1], delayed, offset=offset\n)\nprint(np.array_equal(reference[500:600], aligned_audio[500:600]))  # True\n```\n\nIn this example, we first create a random numpy array. We then call the `find_best_alignment_offset`\nmethod to find the best offset to align two arrays, and we use the align method to align\nthe arrays. The np.array_equal method checks if two arrays are equal, demonstrating the\nsuccessful alignment of the two original arrays.\n\n# Tips\n\n* For more reliable alignments, filter out unwanted/unrelated sounds before passing the audio snippets to fast-align-audio. E.g. if you are aligning two speech recordings, you could band-pass filter and/or denoise them first.\n* This library assumes that the delay is fixed throughout the audio snippet. If you need something that aligns audio tracks in a dynamic way (e.g. due to distance between microphones changing over time), look elsewhere.\n* The `\"mse\"` method is sensitive to loudness differences. If you use this method, make sure the two input audio snippets have roughly the same loudness\n* This lib only works well for small offsets, like up to 500 ms, and suitable audio file durations, like for example between 3 and 45 seconds. If you have large audio files with large offsets between them, a different algorithm may be required to solve the problem well.\n\n# Changelog\n\n## [0.4.0] - 2025-03-18\n\n### Added\n\n* Distribute source (.tar.gz) on PyPI in addition to wheels\n\n### Changed\n\n* **Breaking change**: The first argument of `align_delayed_signal_with_reference`, is now `reference_length` (`int`) instead of `reference_signal` (`NDArray[np.float32]`)\n* Target numpy 2.x instead of 1.x. If you still depend on numpy 1.x, you need an older version of fast-align-audio.\n\n### Removed\n\n* Remove support for Python 3.8\n* Remove musllinux from the build matrix\n\nFor the complete changelog, go to [CHANGELOG.md](CHANGELOG.md)\n\n# Development\n\n* Install dev/build/test dependencies as denoted in setup.py\n* `python setup.py develop`\n* `pytest`\n\n# Acknowledgements\n\nOriginal C implementation by jonashaag. Now maintained/backed by [Nomono](https://nomono.co/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnomonosound%2Ffast-align-audio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnomonosound%2Ffast-align-audio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnomonosound%2Ffast-align-audio/lists"}