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
clip		The clip to load audio from.	required
start	int	Start byte.	required
end		End byte.	required
speed	float	Speed of the audio.	1
time_expansion	float	Time expansion factor.	1
start_time	float | None	Start time in seconds.	None
end_time	float | None	End time in seconds.	None

Returns:

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