Whombat Python API

whombat.api

Python API for Whombat.

Functions

compute_spectrogram(recording, start_time, end_time, audio_parameters, spectrogram_parameters, audio_dir=None)

Compute a spectrogram for a recording.

Parameters:

Name	Type	Description	Default
recording	Recording	The recording to compute the spectrogram for.	required
start_time	float	Start time in seconds.	required
end_time	float	End time in seconds.	required
audio_dir	Path | None	The directory where the audio files are stored.	None
spectrogram_parameters	SpectrogramParameters	Spectrogram parameters.	required

Returns:

Type	Description
DataArray	Spectrogram image.

create_session(db_url=DEFAULT_DB_URL) async

Create a database session.

This function creates a database session that can be used to interact with the database.

It is a context manager, so it can be used with the async with syntax.

Parameters:

Name	Type	Description	Default
db_url	str	The database URL to use, by default it is set to sqlite+aiosqlite://, which is an in-memory database.	DEFAULT_DB_URL

Yields:

Name	Type	Description
session	AsyncSession	The database session.

Examples:

To create a database session, use the async with syntax.

async with create_session() as session:
    # Do stuff with the session
    # ...

You can specify a database URL to use.

async with create_session("sqlite+aiosqlite:///my_db.db") as session:
    # Do stuff with the session
    # ...

Note

This function is asynchronous, so it must be called with the await keyword.

find_feature(features, feature_name, default=None)

Find a feature from a list of features by its name.

Helper function for finding a feature by name. Returns the first feature with the given name, or a default value if no feature is found.

Parameters:

Name	Type	Description	Default
features	Sequence[Feature]	The features to search.	required
feature_name	str	The name of the feature to find.	required
default	Any	The default value to return if the feature is not found.	None

Returns:

Name	Type	Description
feature	Feature | None	The feature, or the default value if the feature was not found.

find_feature_value(features, feature_name, default=None)

Find a the value of a feature from a list of features by its name.

Parameters:

Name	Type	Description	Default
features	Sequence[Feature]	The features to search.	required
feature_name	str	The name of the feature to find.	required
default	Any	The default value to return if the feature is not found.	None

Returns:

Name	Type	Description
value	float | None	The feature value, or the default value if the feature was not found.

find_tag(tags, key, default=None)

Find a tag from a list of tags by its key.

Helper function for finding a tag by key. Returns the first tag with the given key, or a default value if no tag is found.

Parameters:

Name	Type	Description	Default
tags	Sequence[Tag]	The tags to search.	required
key	str	The key to search for.	required
default	Any	The default value to return if the tag is not found.	None

Returns:

Name	Type	Description
tag	Tag | None	The tag, or the default value if the tag was not found.

find_tag_value(tags, key, default=None)

Find a the value of a tag from a list of tags by its key.

Parameters:

Name	Type	Description	Default
tags	Sequence[Tag]	The tags to search.	required
key	str	The key to search for.	required
default	Any	The default value to return if the tag is not found.	None

Returns:

Name	Type	Description
value	float | None	The tag value, or the default value if the tag was not found.

load_audio(recording, start_time=None, end_time=None, audio_dir=None, audio_parameters=None)

Load audio.

Parameters:

Name	Type	Description	Default
recording	Recording	The recording to load audio from.	required
start_time	float | None	Start time in seconds.	None
end_time	float | None	End time in seconds.	None
audio_dir	Path | None	The directory where the audio files are stored.	None
audio_parameters	AudioParameters | None	Audio parameters.	None

Returns:

Type	Description
bytes	Audio data.

load_clip_bytes(path, start, speed=1, frames=8192, time_expansion=1, start_time=None, end_time=None, bit_depth=16)

Load audio.

Parameters:

Name	Type	Description	Default
path	Path	The path to the audio file.	required
start	int	Start byte.	required
speed	float	The factor by which to speed up or slow down the audio. By default, it is 1.	1
frames	int	The number of audio frames to read at a time.	8192
time_expansion	float	Time expansion factor of the audio. By default, it is 1.	1
start_time	float | None	The time in seconds at which to start reading the audio.	None
end_time	float | None	The time in seconds at which to stop reading the audio.	None
bit_depth	int	The bit depth of the resulting audio. By default, it is 16 bits.	16

Returns:

Type	Description
bytes	Loaded audio data in bytes
start	Start byte
end	End byte
filesize	Total size of clip in bytes.