Skip to content

# 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.