AudioLoader

loader.AudioLoader()

Load audio file metadata for creating physical timelines.

AudioLoader extracts metadata from audio files without loading the actual sample data. This is efficient for creating DiscretePhysicalTimelines that represent audio files in the TimeToAlign! framework.

The loader automatically: - Detects the best available backend (soundfile > mutagen > wave) - Extracts sample count, sample rate, channels, and format info - Provides methods to create timelines with appropriate C-maps

Supported formats depend on installed backends: - soundfile: WAV, FLAC, OGG, AIFF, and many more (via libsndfile) - mutagen: MP3, M4A, FLAC, OGG (metadata only, may not have exact sample count) - wave (builtin): WAV only

Examples

>>> loader = AudioLoader()
>>> loader.load("recording.wav")
>>> loader.n_samples
7938048
>>> loader.sample_rate
44100
>>> loader.duration_seconds
180.0

>>> # Create a timeline
>>> timeline = loader.create_timeline(uid="my_audio")
>>> timeline.unit
<TimeUnit.samples: 'samples'>
>>> timeline.length
Coordinate(7938048, samples)

>>> # The timeline has a SamplesToSeconds C-map attached
>>> from timetoalign.core import TimeUnit
>>> timeline.get_timestamp(44100).get_unit(TimeUnit.seconds)
1.0

Attributes

Name	Type	Description
audio_info	AudioInfo	Parsed audio metadata (after loading).

Methods

Name	Description
create_samples_to_seconds_map	Create a SamplesToSeconds conversion map for this audio.
create_timeline	Create a DiscretePhysicalTimeline from the loaded audio.
from_file	Load an audio file and return the loader (convenience constructor).

create_samples_to_seconds_map

loader.AudioLoader.create_samples_to_seconds_map()

Create a SamplesToSeconds conversion map for this audio.

Returns

Name	Type	Description
	'SamplesToSeconds'	A SamplesToSeconds C-map configured with this audio’s sample rate.

Raises

Name	Type	Description
	RuntimeError	If no audio file has been loaded.

create_timeline

loader.AudioLoader.create_timeline(uid=None, name=None, attach_cmap=True)

Create a DiscretePhysicalTimeline from the loaded audio.

The timeline is created with: - unit=TimeUnit.samples - length=n_samples - Optionally, a SamplesToSeconds C-map for coordinate conversion

Parameters

Name	Type	Description	Default
uid	str | None	Unique identifier for the timeline. If None, uses filename.	None
name	str | None	Human-readable name. If None, uses filename.	None
attach_cmap	bool	If True, attach a SamplesToSeconds conversion map.	True

Returns

Name	Type	Description
	'DiscretePhysicalTimeline'	A DiscretePhysicalTimeline representing the audio file.

Raises

Name	Type	Description
	RuntimeError	If no audio file has been loaded.

Examples

>>> loader = AudioLoader().load("song.wav")
>>> timeline = loader.create_timeline()
>>> timeline.unit
<TimeUnit.samples: 'samples'>

>>> # Convert sample coordinates to seconds
>>> from timetoalign.core import TimeUnit
>>> timeline.get_timestamp(44100).get_unit(TimeUnit.seconds)
1.0

from_file

loader.AudioLoader.from_file(path)

Load an audio file and return the loader (convenience constructor).

Parameters

Name	Type	Description	Default
path	Path | str	Path to the audio file.	required

Returns

Name	Type	Description
	'AudioLoader'	An AudioLoader with the file already loaded.

Examples

>>> loader = AudioLoader.from_file("song.wav")
>>> print(loader.duration_seconds)