Whombat Python API

whombat.api

Python API for Whombat.

Modules:

Name	Description
annotation_projects	Python API for annotation projects.
annotation_tasks	Python API for interacting with Tasks.
audio	API functions to load audio.
clip_annotations	Python API for clip annotations.
clip_evaluations	API functions to interact with clip evaluations.
clip_predictions	Python API for managing clip predictions.
clips	API functions for interacting with audio clips.
common	Common API functions.
datasets	API functions for interacting with datasets.
evaluation_sets	API functions for interacting with evaluation sets.
evaluations	API functions to interact with evaluations.
features	API functions to interact with feature names.
io	Whombat Input Output Module.
model_runs	API functions to interact with model runs.
notes	API functions to interact with notes.
recordings	API functions for interacting with recordings.
scatterplots
sessions	Python API to manage database sessions.
sound_event_annotations	Python API for sound event annotations.
sound_event_evaluations	API functions to interact with sound event evaluations.
sound_event_predictions	Python API for interacting with Predictions.
sound_events	API functions to interact with sound events.
spectrograms	API functions to generate spectrograms.
tags	API functions to interact with tags.
user_runs
users	Whombat Python API to interact with user objects in the database.

Functions:

Name	Description
compute_spectrogram	Compute a spectrogram for a recording.
create_session	Create a database session.
find_feature	Find a feature from a list of features by its name.
find_feature_value	Find a the value of a feature from a list of features by its name.
find_tag	Find a tag from a list of tags by its key.
find_tag_value	Find a the value of a tag from a list of tags by its key.
load_audio	Load audio.
load_clip_bytes	Load audio.

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.