OpenTimelineIO Music Arrangement
A production-ready Python library for building OpenTimelineIO timelines specifically tailored for music video editing workflows. Generate professional video editing timelines with precise musical timing alignment.
Features
- 🎵 Musical Timeline Generation: Convert musical timing data into OTIO timelines
- 🎬 FCPXML Export: Direct export to Final Cut Pro via OTIO adapters
- 🎯 Precise Alignment: Align video segments to musical downbeats and subdivisions
- 📍 Visual Markers: Generate beat subdivision guides (1/1, 1/2, 1/3, 1/4 notes)
- 🔧 Type Safe: Full type annotations with mypy compatibility
- ✅ Well Tested: 85% test coverage with comprehensive edge case handling
- 📦 Production Ready: Professional code quality with linting and formatting
Installation
pip install otio-music-arrangement
Development Installation
git clone https://github.com/allenday/otio-music-arrangement.git
cd otio-music-arrangement
pip install -e ".[dev,test]"
Quick Start
from otio_music_arrangement import build_timeline_from_audio
# Create a timeline from musical timing data
timeline = build_timeline_from_audio(
audio_path="song.wav",
beats=[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0],
downbeats=[1.0, 3.0, 5.0, 7.0],
segments=[
{"start": 1.0, "end": 5.0, "label": "verse"},
{"start": 5.0, "end": 9.0, "label": "chorus"}
],
subdivision_level=4, # Quarter-note subdivisions
accumulate=True # Show markers on all relevant tracks
)
# Export to FCPXML
import opentimelineio as otio
otio.adapters.write_to_file(timeline, "music_timeline.fcpxml")
Generated Timeline Structure
The library creates a structured timeline with multiple tracks:
- Audio Track: Primary music file
- Segments Track: Video clips for song sections (verse, chorus, bridge, etc.)
- Downbeats Track: Markers at major musical boundaries
- Beats Track: Markers at each beat
- Subdivisions Track: Fine-grained timing markers (optional)
Each track contains placeholder clips with precise markers aligned to musical timing.
API Reference
Core Functions
build_timeline_from_audio()
def build_timeline_from_audio(
audio_path: str,
beats: list[float | int],
downbeats: list[float | int],
segments: list[dict[str, Any]],
subdivision_level: int = 1,
accumulate: bool = False,
) -> otio.schema.Timeline | None
Parameters:
audio_path: Path to the primary audio filebeats: List of beat times in secondsdownbeats: List of downbeat times in secondssegments: List of segment dictionaries with 'start', 'end', 'label' keyssubdivision_level: Beat subdivision level (1=none, 2=half-notes, 4=quarter-notes)accumulate: Whether markers appear on multiple tracks or just the most specific
Returns: OpenTimelineIO Timeline object ready for export
Utility Functions
adjust_segment_times_to_downbeats()
Aligns segment boundaries to the nearest downbeats for musical accuracy.
calculate_subdivision_markers()
Generates precise subdivision timing markers between beats.
Development
Requirements
- Python 3.10+
- OpenTimelineIO >= 0.15
- FFmpeg (for audio probing)
Setup Development Environment
# Clone repository
git clone https://github.com/allenday/otio-music-arrangement.git
cd otio-music-arrangement
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install with development dependencies
pip install -e ".[dev,test]"
# Install pre-commit hooks
pre-commit install
Running Tests
# Run all tests with coverage
pytest tests/ --cov=src/otio_music_arrangement --cov-report=html
# Run specific test file
pytest tests/test_builder.py -v
# Run with real music data
pytest tests/test_builder.py::test_end_to_end_with_real_music_data -v
Code Quality
# Run linting
ruff check src/ tests/
# Format code
ruff format src/ tests/
# Type checking
mypy src/
# Run all quality checks
ruff check src/ tests/ && mypy src/ && pytest tests/ --cov=src/otio_music_arrangement
Building Package
python -m build
Project Structure
otio-music-arrangement/
├── src/otio_music_arrangement/ # Source code
│ ├── __init__.py # Package interface
│ ├── builder.py # Timeline building logic
│ └── timing_utils.py # Musical timing utilities
├── tests/ # Test suite (85% coverage)
│ ├── fixtures/ # Test data (music files)
│ ├── test_builder.py # Timeline builder tests
│ └── test_timing_utils.py # Timing utilities tests
├── htmlcov/ # Coverage reports
├── pyproject.toml # Project configuration
└── README.md # This file
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes with tests
- Ensure all tests pass and coverage remains high
- Run code quality checks (
ruff check,mypy src/) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Testing
The project includes comprehensive tests with real music data:
- Unit Tests: Individual function testing
- Integration Tests: Full workflow validation
- Error Handling: Edge cases and invalid input testing
- Real Data Tests: Using actual music files (
tests/fixtures/)
Test coverage is maintained at 85%+ with detailed HTML reports.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Built on OpenTimelineIO
- Uses otio-fcpx-xml-lite-adapter for FCPXML export
- Music timing analysis powered by librosa
Technical Approach
Core Technology: Uses the opentimelineio library for timeline structure and time conversions with RationalTime precision.
Music Timing Logic: Dedicated utility functions handle musical calculations like aligning segments to downbeats and calculating subdivision timings.
Timeline Building: Creates OTIO Timeline, Track, Clip, and Marker objects based on musical timing data.
Export Ready: Direct export to FCPXML and other NLE formats via OTIO adapters.
Metadata
Release files for otio-music-arrangement 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| otio_music_arrangement-0.1.2.tar.gz | 3.4 MB | Without provenance | Details for otio_music_arrangement-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| otio_music_arrangement-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for otio_music_arrangement-0.1.2-py3-none-any.whl |
Total release size: 3.4 MB
Release files / otio_music_arrangement-0.1.2.tar.gz
| Download URL | otio_music_arrangement-0.1.2.tar.gz |
|---|---|
| Size | 3.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
54c37f254fbeddb74a6e87819d0c83c6e00dbcc98cbfdb0043d3efc6dae21f99
|
|
BLAKE2b-256 checksum How to use checksums |
d2176b5f83307cd20785687ef6ab139379227b4d49f90e7d7d83d3c2d24ca062
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.17
|
Release files / otio_music_arrangement-0.1.2-py3-none-any.whl
| Download URL | otio_music_arrangement-0.1.2-py3-none-any.whl |
|---|---|
| Size | 15.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f8c1d5b92bc2d520b6b5de3b2956d65bac5a5e3f62ce44fdcfe4ff488e84da8b
|
|
BLAKE2b-256 checksum How to use checksums |
cf444ed89713c57d5480efc1adb09cee274707d76c96335e947b016da6114a84
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.17
|
Security for otio-music-arrangement 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.