Schemas

whombat.schemas

Schemas for Whombat data models.

The Whombat Python API returns these schemas to the user, and they are the main way that the user interacts with the data.

Schemas are defined using Pydantic, and are used to validate data before it is inserted into the database, and also to validate data before it is returned to the user.

Most database models have multiple schemas, a main schema that is used to return data to the user, and a create and update schema that is used to validate data before it is inserted into the database.

Attributes

Scale = Literal['amplitude', 'power', 'dB'] module-attribute

Window = Literal['boxcar', 'triang', 'bartlett', 'flattop', 'parzen', 'bohman', 'blackman', 'blackmanharris', 'nuttall', 'barthann', 'hamming', 'hann', 'kaiser'] module-attribute

Classes

AmplitudeParameters

Bases: BaseModel

Parameters for amplitude clamping.

Parameters:

Name	Type	Description	Default
scale	Literal[str, str, str]		'dB'
clamp	bool		False
min_dB	float		-100.0
max_dB	float		0
normalize	bool		True

Attributes

clamp: bool = False class-attribute instance-attribute

Whether to clamp amplitude values.

max_dB: float = 0 class-attribute instance-attribute

Maximum amplitude value.

min_dB: float = -100.0 class-attribute instance-attribute

Minimum amplitude value.

normalize: bool = True class-attribute instance-attribute

Whether to normalize spectrogram before amplitude scaling.

If True, the spectrogram will be normalized to the range [0, 1] before amplitude scaling. In particular dB values are relative to the maximum amplitude value in the spectrogram, and not the maximum possible amplitude value of the recorder.

This can have the effect of making the spectrogram appear noisier than it actually is, since the maximum amplitude value in the spectrogram may be much lower than the maximum possible amplitude value of the recorder.

Also, when visualizing spectrograms in clips, the amplitude scale will be relative to the maximum amplitude value in the clip, and not the maximum of the recording as a whole. This can make it difficult to compare amplitude levels across clips, and will create artificial seams between clips when visualizing spectrograms in recordings.

scale: Scale = 'dB' class-attribute instance-attribute

Scale to use for spectrogram computation.

Functions

check_db_are_negative(value) classmethod

Check that min_dB and max_dB are non positive.

check_min_dB_and_max_dB()

Check that min_dB is less than max_dB.

AnnotationProject

Bases: BaseSchema

Schema for an annotation project.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
name	str		required
description	str		required
annotation_instructions	str | None		None
tags	list[Tag]		[]

Attributes

annotation_instructions: str | None = None class-attribute instance-attribute

Project instructions for annotating.

description: str instance-attribute

A description of the annotation project.

id: int = Field(..., exclude=True) class-attribute instance-attribute

Database ID of the annotation project.

name: str instance-attribute

Name of the annotation project.

tags: list[Tag] = Field(default_factory=list) class-attribute instance-attribute

Tags to be used throughout the annotation project.

uuid: UUID instance-attribute

UUID of the annotation project.

AnnotationProjectCreate

Bases: BaseModel

Schema for creating an annotation project.

Parameters:

Name	Type	Description	Default
name	str		required
description	str		required
annotation_instructions	str | None		None

Attributes

annotation_instructions: str | None = None class-attribute instance-attribute

Project instructions for annotating.

description: str instance-attribute

A description of the annotation project.

name: str instance-attribute

Name of the annotation project.

AnnotationProjectUpdate

Bases: BaseModel

Schema for updating an annotation project.

Parameters:

Name	Type	Description	Default
name	str | None		None
description	str | None		None
annotation_instructions	str | None		None

Attributes

annotation_instructions: str | None = None class-attribute instance-attribute

Project instructions for annotating.

description: str | None = None class-attribute instance-attribute

A description of the annotation project.

name: str | None = None class-attribute instance-attribute

Name of the annotation project.

AnnotationStatusBadge

Bases: BaseSchema

Schema for a task status badge.

Parameters:

Name	Type	Description	Default
state	AnnotationState		required
user	SimpleUser | None		required

Attributes

state: AnnotationState instance-attribute

State of the task.

user: SimpleUser | None instance-attribute

User to whom the status badge refers.

AnnotationStatusBadgeUpdate

Bases: BaseModel

Schema for updating a task status badge.

Parameters:

Name	Type	Description	Default
state	AnnotationState | None		None

Attributes

state: AnnotationState | None = None class-attribute instance-attribute

State of the task.

AnnotationTask

Bases: BaseSchema

Schema for a task.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
status_badges	list[AnnotationStatusBadge]		required

Attributes

id: int = Field(..., exclude=True) class-attribute instance-attribute

Database ID of the task.

status_badges: list[AnnotationStatusBadge] instance-attribute

Status badges for the task.

uuid: UUID instance-attribute

UUID of the task.

AnnotationTaskCreate

Bases: BaseModel

Schema for creating a new task.

AnnotationTaskNote

Bases: BaseSchema

Schema for a task note.

Parameters:

Name	Type	Description	Default
note	Note		required
task_annotation_uuid	UUID		required

Attributes

note: Note instance-attribute

Note attached to this annotation.

task_annotation_uuid: UUID instance-attribute

UUID of the task annotation this note is attached to.

AnnotationTaskUpdate

Bases: BaseModel

Schema for updating a task.

Parameters:

Name	Type	Description	Default
uuid	UUID | None		None

Attributes

uuid: UUID | None = None class-attribute instance-attribute

AudioParameters

Bases: ResamplingParameters, FilteringParameters

Parameters for audio loading.

BaseSchema

Bases: BaseModel

Base class for all schemas in whombat.

All schemas should inherit from this class, either directly or indirectly.

Parameters:

Name	Type	Description	Default
created_on	datetime		datetime.datetime(2024, 12, 4, 16, 28, 42, 673443, tzinfo=datetime.timezone.utc)

Attributes

created_on: datetime.datetime = Field(repr=False, default_factory=lambda: datetime.datetime.now(datetime.timezone.utc)) class-attribute instance-attribute

model_config = ConfigDict(from_attributes=True) class-attribute instance-attribute

Clip

Bases: BaseSchema

Schema for Clip objects returned to the user.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
start_time	float		required
end_time	float		required
recording	Recording		required
features	list[Feature]		[]

Attributes

end_time: float instance-attribute

The end time of the clip.

features: list[Feature] = Field(default_factory=list) class-attribute instance-attribute

The features associated with the clip.

id: int = Field(..., exclude=True) class-attribute instance-attribute

The database id of the clip.

recording: Recording instance-attribute

Recording information for the clip.

start_time: float instance-attribute

The start time of the clip.

uuid: UUID instance-attribute

The unique identifier of the clip.

ClipAnnotation

Bases: BaseSchema

Schema for an ClipAnnotation.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
clip	Clip		required
notes	list[Note]	Notes attached to this annotation.	[]
tags	list[Tag]	Tags attached to this annotation.	[]
sound_events	list[SoundEventAnnotation]	Annotated sound events attached to this clip.	[]

Attributes

clip: Clip instance-attribute

Clip this annotation is attached to.

id: int = Field(..., exclude=True) class-attribute instance-attribute

Database ID of this annotation.

notes: list[Note] = Field(default_factory=list, description='Notes attached to this annotation.') class-attribute instance-attribute

sound_events: list[SoundEventAnnotation] = Field(default_factory=list, description='Annotated sound events attached to this clip.') class-attribute instance-attribute

tags: list[Tag] = Field(default_factory=list, description='Tags attached to this annotation.', alias_priority=10000) class-attribute instance-attribute

uuid: UUID instance-attribute

ClipAnnotationCreate

Bases: BaseModel

Schema for data required to create an ClipAnnotation.

Parameters:

Name	Type	Description	Default
tags	list[Tag]		[]

Attributes

tags: list[Tag] = Field(default_factory=list) class-attribute instance-attribute

ClipAnnotationNote

Bases: BaseSchema

Schema for a ClipAnnotationNote.

Parameters:

Name	Type	Description	Default
note	Note		required
clip_annotation_uuid	UUID		required

Attributes

clip_annotation_uuid: UUID instance-attribute

UUID of the ClipAnnotation this note is attached to.

note: Note instance-attribute

Note attached to this annotation.

ClipAnnotationTag

Bases: BaseSchema

Schema for an ClipAnnotationTag.

Parameters:

Name	Type	Description	Default
created_by	SimpleUser | None		required
tag	Tag		required
clip_annotation_uuid	UUID		required

Attributes

clip_annotation_uuid: UUID instance-attribute

UUID of the ClipAnnotation this tag is attached to.

created_by: SimpleUser | None instance-attribute

User who created this annotation tag.

tag: Tag instance-attribute

Tag attached to this annotation.

ClipAnnotationUpdate

Bases: BaseSchema

Schema for data required to update an ClipAnnotation.

Parameters:

Name	Type	Description	Default
uuid	UUID | None		None

Attributes

uuid: UUID | None = None class-attribute instance-attribute

UUID of the annotation.

ClipCreate

Bases: BaseModel

Schema for creating a clip.

Parameters:

Name	Type	Description	Default
start_time	float		required
end_time	float		required

Attributes

end_time: float instance-attribute

The end time of the clip.

start_time: float instance-attribute

The start time of the clip.

Functions

validate_times(values)

Validate that start_time < end_time.

ClipEvaluation

Bases: BaseSchema

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
clip_annotation	ClipAnnotation		required
clip_prediction	ClipPrediction		required
sound_event_evaluations	list[SoundEventEvaluation]		[]
metrics	list[Feature]		[]
score	float		required

Attributes

clip_annotation: ClipAnnotation instance-attribute

Clip annotation used for the evaluation.

clip_prediction: ClipPrediction instance-attribute

Clip prediction being evaluated.

id: int = Field(..., exclude=True) class-attribute instance-attribute

Database ID of the evaluation.

metrics: list[Feature] = Field(default_factory=list) class-attribute instance-attribute

Evaluation metrics.

score: float instance-attribute

Overall score of the evaluation.

sound_event_evaluations: list[SoundEventEvaluation] = Field(default_factory=list) class-attribute instance-attribute

The evaluation of the sound events within the clip.

uuid: UUID instance-attribute

UUID of the Clip Evaluation.

ClipEvaluationCreate

Bases: BaseModel

Schema for creating a new Clip Evaluation.

Parameters:

Name	Type	Description	Default
score	float		required

Attributes

score: float instance-attribute

Overall score of the evaluation.

ClipEvaluationUpdate

Bases: BaseModel

Schema for updating an existing Clip Evaluation.

Parameters:

Name	Type	Description	Default
score	float | None		None
uuid	UUID | None		None

Attributes

score: float | None = None class-attribute instance-attribute

Overall score of the evaluation.

uuid: UUID | None = None class-attribute instance-attribute

UUID of the Clip Evaluation.

ClipPrediction

Bases: BaseSchema

Schema for a clip prediction.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
clip	Clip		required
sound_events	list[SoundEventPrediction]		[]
tags	list[ClipPredictionTag]		[]

Attributes

clip: Clip instance-attribute

Clip to which this prediction belongs.

id: int = Field(..., exclude=True) class-attribute instance-attribute

Database ID of the prediction.

sound_events: list[SoundEventPrediction] = Field(default_factory=list) class-attribute instance-attribute

Sound event predictions of the clip.

tags: list[ClipPredictionTag] = Field(default_factory=list) class-attribute instance-attribute

Tags of the prediction.

uuid: UUID instance-attribute

UUID of the prediction.

ClipPredictionCreate

Bases: BaseModel

Schema for creating a new clip prediction.

Parameters:

Name	Type	Description	Default
tags	list[PredictedTag]		[]

Attributes

tags: list[PredictedTag] = Field(default_factory=list) class-attribute instance-attribute

Tags of the prediction.

ClipPredictionTag

Bases: BaseSchema

Schema for a clip prediction tag.

Parameters:

Name	Type	Description	Default
tag	Tag		required
score	float		required

Attributes

score: float instance-attribute

Confidence of the prediction.

tag: Tag instance-attribute

Tag of the prediction.

ClipPredictionUpdate

Bases: BaseModel

Schema for updating a clip prediction.

Parameters:

Name	Type	Description	Default
uuid	UUID | None		None

Attributes

uuid: UUID | None = None class-attribute instance-attribute

UUID of the prediction.

ClipUpdate

Bases: BaseModel

Schema for updating a clip.

Parameters:

Name	Type	Description	Default
uuid	UUID | None		None

Attributes

uuid: UUID | None = None class-attribute instance-attribute

The unique identifier of the clip.

Dataset

Bases: BaseSchema

Schema for Dataset objects returned to the user.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
audio_dir	Path		required
name	str		required
description	str | None		required
recording_count	int		0

Attributes

audio_dir: Path instance-attribute

The path to the directory containing the audio files.

description: str | None instance-attribute

The description of the dataset.

id: int = Field(..., exclude=True) class-attribute instance-attribute

The database id of the dataset.

name: str instance-attribute

The name of the dataset.

recording_count: int = 0 class-attribute instance-attribute

The number of recordings in the dataset.

uuid: UUID instance-attribute

The uuid of the dataset.

DatasetCreate

Bases: BaseModel

Schema for Dataset objects created by the user.

Parameters:

Name	Type	Description	Default
audio_dir	Path		required
name	str		required
description	str | None		None

Attributes

audio_dir: DirectoryPath instance-attribute

The path to the directory containing the audio files.

description: str | None = Field(None) class-attribute instance-attribute

The description of the dataset.

name: str = Field(..., min_length=1) class-attribute instance-attribute

The name of the dataset.

DatasetFile

Bases: BaseModel

Schema for DatasetFile objects returned to the user.

Parameters:

Name	Type	Description	Default
path	Path		required
state	FileState		required

Attributes

path: Path instance-attribute

The path to the file.

state: FileState instance-attribute

The state of the file.

DatasetRecording

Bases: BaseSchema

Schema for DatasetRecording objects returned to the user.

Parameters:

Name	Type	Description	Default
recording	Recording		required
state	FileState		<FileState.REGISTERED: 'registered'>
path	Path		required

Attributes

path: Path instance-attribute

The path to the recording in the dataset directory.

recording: Recording instance-attribute

The uuid of the recording.

state: FileState = Field(default=FileState.REGISTERED) class-attribute instance-attribute

The state of the file.

DatasetRecordingCreate

Bases: BaseModel

Schema for DatasetRecording objects created by the user.

Parameters:

Name	Type	Description	Default
path	Path		required

Attributes

path: Path instance-attribute

The path to the recording in the dataset directory.

DatasetUpdate

Bases: BaseModel

Schema for Dataset objects updated by the user.

Parameters:

Name	Type	Description	Default
audio_dir	Annotated[Path, PathType] | None		None
name	str | None		None
description	str | None		None

Attributes

audio_dir: DirectoryPath | None = None class-attribute instance-attribute

The path to the directory containing the audio files.

description: str | None = None class-attribute instance-attribute

The description of the dataset.

name: str | None = Field(default=None, min_length=1) class-attribute instance-attribute

The name of the dataset.

Evaluation

Bases: BaseSchema

Evaluation schema.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
score	float		required
task	str		required
metrics	list[Feature]		[]

Attributes

id: int = Field(..., exclude=True) class-attribute instance-attribute

Dataset identifier of the evaluation.

metrics: list[Feature] = Field(default_factory=list) class-attribute instance-attribute

List of metrics of the evaluation.

score: float instance-attribute

Overall score of the evaluation.

task: str instance-attribute

Task of the evaluation.

uuid: UUID instance-attribute

EvaluationCreate

Bases: BaseModel

Evaluation creation schema.

Parameters:

Name	Type	Description	Default
score	float		0
task	str		required

Attributes

score: float = Field(default=0, ge=0, le=1) class-attribute instance-attribute

Overall score of the evaluation.

task: str instance-attribute

Task of the evaluation.

EvaluationSet

Bases: BaseSchema

Schema for EvaluationSet objects returned to the user.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
name	str		required
description	str | None		required
task	PredictionTypes		required
tags	list[Tag]		[]

Attributes

description: str | None instance-attribute

The description of the evaluation set.

id: int = Field(..., exclude=True) class-attribute instance-attribute

The id of the evaluation set.

name: str instance-attribute

The name of the evaluation set.

tags: list[Tag] = Field(default_factory=list) class-attribute instance-attribute

The tags to use for the evaluation set.

task: PredictionTypes instance-attribute

The name of the task the evaluation set is used for.

uuid: UUID instance-attribute

The uuid of the evaluation set.

EvaluationSetCreate

Bases: BaseModel

Schema for creating EvaluationSet objects.

Parameters:

Name	Type	Description	Default
name	str		required
description	str | None		None
task	PredictionTypes		required

Attributes

description: str | None = Field(default=None) class-attribute instance-attribute

The description of the evaluation set.

name: str = Field(..., min_length=1) class-attribute instance-attribute

The name of the evaluation set.

task: PredictionTypes = Field(..., min_length=1) class-attribute instance-attribute

The name of the task the evaluation set is used for.

EvaluationSetUpdate

Bases: BaseModel

Schema for updating EvaluationSet objects.

Parameters:

Name	Type	Description	Default
name	str | None		None
description	str | None		None

Attributes

description: str | None = None class-attribute instance-attribute

The description of the evaluation set.

name: str | None = Field(default=None, min_length=1) class-attribute instance-attribute

The name of the evaluation set.

EvaluationUpdate

Bases: BaseModel

Evaluation update schema.

Parameters:

Name	Type	Description	Default
uuid	UUID | None		None
score	float | None		None
task	str | None		None

Attributes

score: float | None = None class-attribute instance-attribute

Overall score of the evaluation.

task: str | None = None class-attribute instance-attribute

Task of the evaluation.

uuid: UUID | None = None class-attribute instance-attribute

Unique identifier of the evaluation.

Feature

Bases: BaseModel

Schema for Feature objects returned to the user.

Parameters:

Name	Type	Description	Default
name	str		required
value	float		required

Attributes

model_config = ConfigDict(from_attributes=True) class-attribute instance-attribute

name: str instance-attribute

The name of the feature.

value: float instance-attribute

The value of the feature.

FeatureName

Bases: BaseSchema

Schema for FeatureName objects returned to the user.

Parameters:

Name	Type	Description	Default
id	int		required
name	str		required

Attributes

id: int = Field(..., exclude=True) class-attribute instance-attribute

The database id of the feature name.

name: str instance-attribute

The name of the feature.

FeatureNameCreate

Bases: BaseModel

Schema for FeatureName objects created by the user.

Parameters:

Name	Type	Description	Default
name	str		required

Attributes

name: str instance-attribute

The name of the feature.

FeatureNameUpdate

Bases: BaseModel

Schema for FeatureName objects updated by the user.

Parameters:

Name	Type	Description	Default
name	str		required

Attributes

name: str instance-attribute

The name of the feature.

FileState

Bases: Enum

The state of a file in a dataset.

Datasets can contain files that are not registered in the database. This can happen if the file was added to the dataset directory after the dataset was registered. Additionally, files can be registered in the database but missing from the dataset directory. This can happen if the file was removed from the dataset directory after the dataset was registered.

The state of a file can be one of the following:

• missing: The file is not registered in the database and is missing.

• registered: The file is registered in the database and is present.

• unregistered: The file is not registered in the database but is present in the dataset directory.

Attributes

MISSING = 'missing' class-attribute instance-attribute

If the recording is registered but the file is missing.

REGISTERED = 'registered' class-attribute instance-attribute

If the recording is registered and the file is present.

UNREGISTERED = 'unregistered' class-attribute instance-attribute

If the recording is not registered but the file is present.

ModelRun

Bases: ModelRunCreate

Schema of a model run as returned to the user.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required

Attributes

id: int = Field(..., exclude=True) class-attribute instance-attribute

The database identifier of the model run.

uuid: UUID instance-attribute

The unique identifier of the model run.

ModelRunCreate

Bases: BaseSchema

Model Run creation schema.

Parameters:

Name	Type	Description	Default
name	str		required
version	str		required
description	str | None		None

Attributes

description: str | None = None class-attribute instance-attribute

A description of the model used to generate the model run.

name: str instance-attribute

Name of the model used to generate the model run.

version: str instance-attribute

Version of the model used to generate the model run.

ModelRunUpdate

Bases: BaseSchema

Model Run update schema.

Parameters:

Name	Type	Description	Default
name	str | None		None
version	str | None		None
description	str | None		None

Attributes

description: str | None = None class-attribute instance-attribute

The description of the model used to generate the model run.

name: str | None = None class-attribute instance-attribute

The name of the model used to generate the model run.

version: str | None = None class-attribute instance-attribute

The version of the model used to generate the model run.

Note

Bases: BaseSchema

Schema for Note objects returned to the user.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
message	str		required
is_issue	bool		required
created_by	SimpleUser | None		required

Attributes

created_by: SimpleUser | None instance-attribute

The user who created the note.

id: int = Field(..., exclude=True) class-attribute instance-attribute

The database id of the note.

is_issue: bool instance-attribute

Whether the note is an issue.

message: str instance-attribute

The message of the note.

uuid: UUID instance-attribute

The uuid of the note.

NoteCreate

Bases: BaseModel

Schema for creating notes.

This schema is used when creating notes from the API as the user does not need to provide the id of the user who created the note.

Parameters:

Name	Type	Description	Default
message	str		required
is_issue	bool		False

Attributes

is_issue: bool = False class-attribute instance-attribute

message: str = Field(min_length=1, max_length=1000) class-attribute instance-attribute

NoteUpdate

Bases: BaseModel

Schema for updating notes.

Parameters:

Name	Type	Description	Default
message	str | None		None
is_issue	bool | None		None

Attributes

is_issue: bool | None = None class-attribute instance-attribute

Whether the note is an issue.

message: str | None = Field(None, min_length=1, max_length=1000) class-attribute instance-attribute

The message of the note.

Page

Bases: BaseModel, Generic[M]

A page of results.

Parameters:

Name	Type	Description	Default
items	Sequence[TypeVar]		required
total	int		required
offset	int		required
limit	int		required

Attributes

items: Sequence[M] instance-attribute

limit: int instance-attribute

offset: int instance-attribute

total: int instance-attribute

PluginInfo

Bases: BaseModel

Plugin information.

Parameters:

Name	Type	Description	Default
name	str	Plugin name.	required
url	str	Route to the plugin pages.	required
description	str | None	Plugin description.	None
version	str | None	Plugin version.	None
thumbnail	str | None	Plugin thumbnail.	None
attribution	str | None	Plugin attribution.	None

Attributes

attribution: str | None = Field(default=None, description='Plugin attribution.') class-attribute instance-attribute

description: str | None = Field(default=None, description='Plugin description.') class-attribute instance-attribute

name: str = Field(..., description='Plugin name.') class-attribute instance-attribute

thumbnail: str | None = Field(default=None, description='Plugin thumbnail.') class-attribute instance-attribute

url: str = Field(..., description='Route to the plugin pages.') class-attribute instance-attribute

version: str | None = Field(default=None, description='Plugin version.') class-attribute instance-attribute

PredictedTag

Bases: BaseSchema

Schema for PredictedTag objects returned to the user.

Parameters:

Name	Type	Description	Default
tag	Tag		required
score	float		required

Attributes

score: float instance-attribute

The confidence score for the assignment of the tag.

tag: Tag instance-attribute

The tag that was predicted.

Recording

Bases: BaseSchema

Schema for Recording objects returned to the user.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
path	Path		required
date	date | None		required
time	time | None		required
latitude	float | None		required
longitude	float | None		required
time_expansion	float		required
hash	str		required
duration	float		required
channels	int		required
samplerate	int		required
rights	str | None		required
tags	list[Tag]		[]
features	list[Feature]		[]
notes	list[Note]		[]
owners	list[SimpleUser]		[]

Attributes

channels: int instance-attribute

The number of channels in the audio file.

date: datetime.date | None instance-attribute

The date of the recording.

duration: float instance-attribute

The duration of the audio file in seconds.

This is the duration of the original audio file, not the time expanded version. This can vary depending on the time expansion factor. If the stored file has a duration of 10 seconds and a time expansion factor is 2, this means that the original recording was 5 seconds long. So the duration of the original recording is 5 seconds, not 10.

features: list[Feature] = Field(default_factory=list) class-attribute instance-attribute

The features associated with the recording.

hash: str instance-attribute

The md5 hash of the audio file.

id: int = Field(..., exclude=True) class-attribute instance-attribute

The database id of the recording.

latitude: float | None instance-attribute

The latitude of the recording.

longitude: float | None instance-attribute

The longitude of the recording.

notes: list[Note] = Field(default_factory=list) class-attribute instance-attribute

The notes associated with the recording.

owners: list[SimpleUser] = Field(default_factory=list) class-attribute instance-attribute

The users that own the recording.

path: Path instance-attribute

The path to the audio file, relative to the audio directory.

rights: str | None instance-attribute

A text describing the usage rights of the recording.

samplerate: int instance-attribute

The sample rate of the audio file in Hz.

This is the sample rate of the original audio file, not the time expanded version. This can vary depending on the time expansion factor. If the stored file has a sample rate of 44100 Hz and a time expansion factor is 2, this means that the original recording had a sample rate of 88200 Hz. So the sample rate of the original recording is 88200 Hz, not 44100 Hz.

tags: list[Tag] = Field(default_factory=list) class-attribute instance-attribute

The tags associated with the recording.

time: datetime.time | None instance-attribute

The time of the recording.

time_expansion: float instance-attribute

The time expansion factor of the recording.

uuid: UUID instance-attribute

The UUID of the recording.

RecordingCreate

Bases: BaseModel

Data for Recording creation.

Parameters:

Name	Type	Description	Default
date	date | None		None
time	time | None		None
latitude	float | None		None
longitude	float | None		None
time_expansion	float		1.0
rights	str | None		None
path	Path		required

Attributes

date: datetime.date | None = None class-attribute instance-attribute

The date of the recording.

latitude: float | None = Field(default=None, ge=-90, le=90) class-attribute instance-attribute

The latitude of the recording.

longitude: float | None = Field(default=None, ge=-180, le=180) class-attribute instance-attribute

The longitude of the recording.

path: FilePath instance-attribute

The path to the audio file.

rights: str | None = None class-attribute instance-attribute

A text describing the usage rights of the recording.

time: datetime.time | None = None class-attribute instance-attribute

The time of the recording.

time_expansion: float = Field(default=1.0, gt=0) class-attribute instance-attribute

The time expansion factor of the recording.

Functions

is_an_audio_file(v)

Validate that the given path is an audio file.

RecordingNote

Bases: BaseSchema

Schema for RecordingNote objects.

Parameters:

Name	Type	Description	Default
recording_uuid	UUID		required
note	Note		required

Attributes

note: Note instance-attribute

recording_uuid: UUID instance-attribute

RecordingTag

Bases: BaseSchema

Schema for RecordingTag objects.

Parameters:

Name	Type	Description	Default
recording_uuid	UUID		required
tag	Tag		required

Attributes

recording_uuid: UUID instance-attribute

The UUID of the recording.

tag: Tag instance-attribute

The tag associated with the recording.

RecordingUpdate

Bases: BaseModel

Schema for Recording objects updated by the user.

Parameters:

Name	Type	Description	Default
date	date | None		None
time	time | None		None
latitude	float | None		None
longitude	float | None		None
path	Annotated[Path, PathType] | None		None
time_expansion	float | None		None
rights	str | None		None

Attributes

date: datetime.date | None = None class-attribute instance-attribute

The date of the recording.

latitude: float | None = Field(default=None, ge=-90, le=90) class-attribute instance-attribute

The latitude of the recording.

longitude: float | None = Field(default=None, ge=-180, le=180) class-attribute instance-attribute

The longitude of the recording.

path: FilePath | None = None class-attribute instance-attribute

New path to the audio file.

rights: str | None = None class-attribute instance-attribute

A text describing the usage rights of the recording.

time: datetime.time | None = None class-attribute instance-attribute

The time of the recording.

time_expansion: float | None = Field(default=None, gt=0) class-attribute instance-attribute

New time expansion factor of the recording.

STFTParameters

Bases: BaseModel

Parameters for STFT computation.

Parameters:

Name	Type	Description	Default
window_size	float		0.025
overlap	float		0.5
window	Literal[str, str, str, str, str, str, str, str, str, str, str, str, str]		'hann'

Attributes

overlap: float = Field(default=0.5, gt=0.0, le=1.0) class-attribute instance-attribute

Window overlap as a fraction of window size.

window: Window = 'hann' class-attribute instance-attribute

Window function.

window_size: float = 0.025 class-attribute instance-attribute

Size of FFT window in seconds.

Functions

check_positive(value) classmethod

Check that window size and hop size are positive.

SimpleUser

Bases: BaseSchema

Schema for User objects returned to the user.

Parameters:

Name	Type	Description	Default
id	UUID		required
username	str		required
email	EmailStr | None		None
name	str | None		None
is_active	bool | None		False
is_superuser	bool | None		False
is_verified	bool | None		False

Attributes

email: EmailStr | None = None class-attribute instance-attribute

id: uuid.UUID instance-attribute

is_active: bool | None = False class-attribute instance-attribute

is_superuser: bool | None = False class-attribute instance-attribute

is_verified: bool | None = False class-attribute instance-attribute

name: str | None = None class-attribute instance-attribute

username: str instance-attribute

SoundEvent

Bases: BaseSchema

Public schema for handling sound events.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
geometry	TimeStamp | TimeInterval | Point | LineString | Polygon | BoundingBox | MultiPoint | MultiLineString | MultiPolygon		required
geometry_type	Literal[str] | Literal[str] | Literal[str] | Literal[str] | Literal[str] | Literal[str] | Literal[str] | Literal[str] | Literal[str]		required
features	list[Feature]		[]

Attributes

features: list[Feature] = Field(default_factory=list) class-attribute instance-attribute

The features associated with the sound event.

geometry: Geometry = Field(..., discriminator='type') class-attribute instance-attribute

geometry_type: GeometryType instance-attribute

id: int = Field(..., exclude=True) class-attribute instance-attribute

The id of the sound event.

uuid: UUID instance-attribute

The uuid of the sound event.

SoundEventAnnotation

Bases: BaseSchema

Schema for an SoundEventAnnotation.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
created_by	SimpleUser | None		required
sound_event	SoundEvent		required
notes	list[Note]		[]
tags	list[Tag]		[]

Attributes

created_by: SimpleUser | None instance-attribute

User who created this annotation.

id: int = Field(..., exclude=True) class-attribute instance-attribute

Database ID of this annotation.

notes: list[Note] = Field(default_factory=list) class-attribute instance-attribute

Notes attached to this annotation.

sound_event: SoundEvent instance-attribute

Sound event this annotation is attached to.

tags: list[Tag] = Field(default_factory=list) class-attribute instance-attribute

Tags attached to this annotation.

uuid: UUID instance-attribute

UUID of this annotation.

SoundEventAnnotationCreate

Bases: BaseModel

Schema for data required to create an SoundEventAnnotation.

Parameters:

Name	Type	Description	Default
geometry	TimeStamp | TimeInterval | Point | LineString | Polygon | BoundingBox | MultiPoint | MultiLineString | MultiPolygon		required
tags	list[TagCreate]		[]

Attributes

geometry: Geometry = Field(..., discriminator='type') class-attribute instance-attribute

Geometry of this annotation.

tags: list[TagCreate] = Field(default_factory=list) class-attribute instance-attribute

Tags attached to this annotation.

SoundEventAnnotationNote

Bases: BaseSchema

Schema for a SoundEventAnnotationNote.

Parameters:

Name	Type	Description	Default
note	Note		required
sound_event_annotation_uuid	UUID		required

Attributes

note: Note instance-attribute

Note attached to this annotation.

sound_event_annotation_uuid: UUID instance-attribute

UUID of the SoundEventAnnotation this note is attached to.

SoundEventAnnotationTag

Bases: BaseSchema

Schema for a SoundEventAnnotationTag.

Parameters:

Name	Type	Description	Default
tag	Tag		required
created_by	SimpleUser | None		required
sound_event_annotation_uuid	UUID		required

Attributes

created_by: SimpleUser | None instance-attribute

User who created this annotation.

sound_event_annotation_uuid: UUID instance-attribute

UUID of the SoundEventAnnotation this tag is attached to.

tag: Tag instance-attribute

Tag attached to this annotation.

SoundEventAnnotationUpdate

Bases: BaseSchema

Schema for data required to update an SoundEventAnnotation.

Parameters:

Name	Type	Description	Default
geometry	TimeStamp | TimeInterval | Point | LineString | Polygon | BoundingBox | MultiPoint | MultiLineString | MultiPolygon		required

Attributes

geometry: Geometry = Field(..., discriminator='type') class-attribute instance-attribute

Geometry of this annotation.

SoundEventCreate

Bases: BaseModel

Schema for SoundEvent objects created by the user.

Parameters:

Name	Type	Description	Default
geometry	TimeStamp | TimeInterval | Point | LineString | Polygon | BoundingBox | MultiPoint | MultiLineString | MultiPolygon		required

Attributes

geometry: Geometry = Field(..., discriminator='type') class-attribute instance-attribute

The geometry of the sound event.

geometry_type: GeometryType property

Return the type of geometry used to mark the sound event.

SoundEventEvaluation

Bases: BaseSchema

Schema for a sound event evaluation.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
source	SoundEventPrediction | None		required
target	SoundEventAnnotation | None		required
affinity	float		required
score	float		required
metrics	list[Feature]		[]

Attributes

affinity: float instance-attribute

Affinity of the match between the source and target.

id: int = Field(..., exclude=True) class-attribute instance-attribute

Database ID of the evaluation.

metrics: list[Feature] = Field(default_factory=list) class-attribute instance-attribute

Evaluation metrics.

score: float instance-attribute

Overall score of the evaluation.

source: SoundEventPrediction | None instance-attribute

Source sound event prediction.

target: SoundEventAnnotation | None instance-attribute

Target sound event annotation.

uuid: UUID instance-attribute

SoundEventEvaluationCreate

Bases: BaseModel

Schema for creating a new sound event evaluation.

Parameters:

Name	Type	Description	Default
affinity	float		required
score	float		required

Attributes

affinity: float instance-attribute

Affinity of the match between the source and target.

score: float instance-attribute

Overall score of the evaluation.

SoundEventEvaluationUpdate

Bases: BaseSchema

Schema for updating a sound event evaluation.

Parameters:

Name	Type	Description	Default
affinity	float | None		None
score	float | None		None
uuid	UUID | None		None

Attributes

affinity: float | None = None class-attribute instance-attribute

Affinity of the match between the source and target.

score: float | None = None class-attribute instance-attribute

Overall score of the evaluation.

uuid: UUID | None = None class-attribute instance-attribute

UUID of the Sound Event Evaluation.

SoundEventPrediction

Bases: BaseSchema

Schema for a sound event prediction.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
sound_event	SoundEvent		required
score	float		required
tags	list[SoundEventPredictionTag]		[]

Attributes

id: int = Field(..., exclude=True) class-attribute instance-attribute

Database ID of the prediction.

score: float instance-attribute

Overall score of the prediction.

sound_event: SoundEvent instance-attribute

Sound event to be predicted.

tags: list[SoundEventPredictionTag] = Field(default_factory=list) class-attribute instance-attribute

Tags of the prediction.

uuid: UUID instance-attribute

UUID of the prediction.

SoundEventPredictionCreate

Bases: BaseModel

Schema for creating a new sound event prediction.

Parameters:

Name	Type	Description	Default
geometry	TimeStamp | TimeInterval | Point | LineString | Polygon | BoundingBox | MultiPoint | MultiLineString | MultiPolygon		required
score	float		required

Attributes

geometry: Geometry = Field(..., discriminator='type') class-attribute instance-attribute

Geometry of this sound event prediction.

score: float instance-attribute

Overall score of the prediction.

SoundEventPredictionTag

Bases: BaseSchema

Schema for a sound event prediction tag.

Parameters:

Name	Type	Description	Default
score	float		required
tag	Tag		required

Attributes

score: float instance-attribute

Score of the tag.

tag: Tag instance-attribute

Tag.

SoundEventPredictionUpdate

Bases: BaseModel

Schema for updating a sound event prediction.

Parameters:

Name	Type	Description	Default
uuid	UUID | None		required
score	float | None		required

Attributes

score: float | None instance-attribute

Overall score of the prediction.

uuid: UUID | None instance-attribute

UUID of the prediction.

SoundEventUpdate

Bases: BaseSchema

Schema for SoundEvent objects updated by the user.

Parameters:

Name	Type	Description	Default
geometry	TimeStamp | TimeInterval | Point | LineString | Polygon | BoundingBox | MultiPoint | MultiLineString | MultiPolygon		required

Attributes

geometry: Geometry = Field(..., discriminator='type') class-attribute instance-attribute

The geometry of the sound event.

SpectrogramParameters

Bases: STFTParameters, AmplitudeParameters

Parameters for spectrogram computation.

Parameters:

Name	Type	Description	Default
channel	int		0
pcen	bool		True
cmap	str		'gray'

Attributes

channel: int = 0 class-attribute instance-attribute

Channel to use for spectrogram computation.

cmap: str = 'gray' class-attribute instance-attribute

Colormap to use for spectrogram.

pcen: bool = True class-attribute instance-attribute

Whether to apply PCEN for de-noising.

Tag

Bases: BaseSchema

Schema for Tag objects returned to the user.

Parameters:

Name	Type	Description	Default
id	int		required
key	str		required
value	str		required

Attributes

id: int = Field(..., exclude=True) class-attribute instance-attribute

Database ID of the tag.

key: str instance-attribute

Key of the tag.

value: str instance-attribute

Value of the tag.

TagCount

Bases: BaseSchema

Schema for TagCount objects returned to the user.

Parameters:

Name	Type	Description	Default
tag	Tag		required
count	int		required

Attributes

count: int instance-attribute

Count of the tag.

tag: Tag instance-attribute

Tag object.

TagCreate

Bases: BaseModel

Schema for creating Tag objects.

Parameters:

Name	Type	Description	Default
key	str		required
value	str		required

Attributes

key: str = Field(min_length=1, max_length=255) class-attribute instance-attribute

Key of the tag.

value: str = Field(min_length=1, max_length=255) class-attribute instance-attribute

Value of the tag.

TagUpdate

Bases: BaseModel

Schema for updating Tag objects.

Parameters:

Name	Type	Description	Default
key	str | None		None
value	str | None		None

Attributes

key: str | None = Field(default=None, min_length=1, max_length=255) class-attribute instance-attribute

Key of the tag.

value: str | None = Field(default=None, min_length=1, max_length=255) class-attribute instance-attribute

Value of the tag.

User

Bases: BaseUser[UUID]

Schema for User objects returned to the user.

Parameters:

Name	Type	Description	Default
username	str		required
name	str | None		None
created_on	datetime		required

Attributes

created_on: datetime.datetime instance-attribute

name: Optional[str] = None class-attribute instance-attribute

username: str instance-attribute

UserCreate

Bases: BaseUserCreate

Schema for User objects created by the user.

Parameters:

Name	Type	Description	Default
username	str		required
name	str | None		None

Attributes

name: str | None = None class-attribute instance-attribute

username: str instance-attribute

UserRun

Bases: BaseSchema

Schema of a user run as returned to the user.

Parameters:

Name	Type	Description	Default
uuid	UUID		required
id	int		required
user	SimpleUser		required

Attributes

id: int = Field(..., exclude=True) class-attribute instance-attribute

The databset identifier of the model run.

user: SimpleUser instance-attribute

The user who created the user run.

uuid: UUID instance-attribute

Unique identifier of the user run.

UserRunCreate

Bases: BaseModel

Model Run creation schema.

UserRunUpdate

Bases: BaseModel

Schema for updating a user run.

Parameters:

Name	Type	Description	Default
uuid	UUID		UUID('c914beb3-473f-4f72-92f5-8eccc038f5c3')

Attributes

uuid: UUID = Field(default_factory=uuid4) class-attribute instance-attribute

Unique identifier of the user run.

UserUpdate

Bases: BaseUserUpdate

Schema for User objects updated by the user.

Parameters:

Name	Type	Description	Default
username	str | None		None
name	str | None		None

Attributes

name: str | None = None class-attribute instance-attribute

username: str | None = None class-attribute instance-attribute