Data#
acoupi.data
#
Data objects for acoupi System.
Classes:
| Name | Description |
|---|---|
BoundingBox |
BoundingBox to locate a sound event in time and frequency. |
Deployment |
A Deployment captures information about the device deployment. |
Detection |
A Detection is a single prediction from a model. |
EventDetection |
Detection for a region that contains exactly one target sound event. |
Message |
The message to be sent to the remote server. |
ModelOutput |
The output of a model. |
ModelOutputInfo |
Lightweight model-output information for management-style queries. |
PredictedTag |
A PredictedTag is a label predicted by a model. |
PredictionType |
Describe what kind of sound pattern a detection refers to. |
PresenceDetection |
Detection for a region where one or more target sounds are present. |
Recording |
A Recording is a single audio file recorded from the microphone. |
Response |
The response from sending a message. |
ResponseStatus |
The status of a message. |
SequenceDetection |
Detection for a region that contains exactly one sequence of sounds. |
TimeInterval |
An interval of time between two times of day. |
Classes#
BoundingBox
#
Bases: BaseModel
BoundingBox to locate a sound event in time and frequency.
All time values are in seconds and all frequency values are in Hz.
Methods:
| Name | Description |
|---|---|
from_coordinates |
Create a BoundingBox from coordinates. |
validate_coordinates |
Validate that the coordinates are within range. |
Attributes:
| Name | Type | Description |
|---|---|---|
coordinates |
Tuple[float, float, float, float]
|
|
model_config |
|
|
type |
str
|
|
Attributes#
coordinates
instance-attribute
#
model_config = ConfigDict(frozen=True)
class-attribute
instance-attribute
#
type = 'BoundingBox'
class-attribute
instance-attribute
#
Methods:#
from_coordinates(start_time, low_freq, end_time, high_freq)
classmethod
#
Create a BoundingBox from coordinates.
validate_coordinates(value)
#
Validate that the coordinates are within range.
Deployment
#
Bases: BaseModel
A Deployment captures information about the device deployment.
This includes the latitude, longitude, and deployment start.
Methods:
| Name | Description |
|---|---|
add_missing_timezone |
|
validate_latitude |
Validate that the latitude are within range. |
validate_longitude |
Validate that the longitude are within range. |
Attributes:
| Name | Type | Description |
|---|---|---|
ended_on |
Optional[AwareDatetime]
|
The datetime when the deployment ended. |
id |
UUID
|
The unique ID of the deployment. |
latitude |
Optional[float]
|
The latitude of the site where the device is deployed. |
longitude |
Optional[float]
|
The longitude of the site where the device is deployed. |
name |
str
|
User provided name of the deployment. |
started_on |
AwareDatetime
|
The datetime when the device was deployed. |
Attributes#
ended_on = None
class-attribute
instance-attribute
#
The datetime when the deployment ended.
id = Field(default_factory=uuid4)
class-attribute
instance-attribute
#
The unique ID of the deployment.
latitude = None
class-attribute
instance-attribute
#
The latitude of the site where the device is deployed.
longitude = None
class-attribute
instance-attribute
#
The longitude of the site where the device is deployed.
name
instance-attribute
#
User provided name of the deployment.
started_on = Field(default_factory=utc_now)
class-attribute
instance-attribute
#
The datetime when the device was deployed.
Methods:#
add_missing_timezone(v)
#
validate_latitude(value)
#
Validate that the latitude are within range.
validate_longitude(value)
#
Validate that the longitude are within range.
Detection
#
Bases: BaseModel
A Detection is a single prediction from a model.
The prediction_type explains what kind of thing the detection refers
to. In most cases, it is easier to use one of the convenience classes
instead of setting this field manually:
PresenceDetectionfor one or more target sounds in a region.SequenceDetectionfor exactly one sequence of related sounds.EventDetectionfor exactly one single sound event.
Methods:
| Name | Description |
|---|---|
validate_score |
Validate that the score is between 0 and 1. |
Attributes:
| Name | Type | Description |
|---|---|---|
detection_score |
float
|
The score of the detection. |
id |
UUID
|
The unique ID of the detection |
location |
Optional[BoundingBox]
|
The location of the detection in the recording. |
model_config |
|
|
prediction_type |
PredictionType
|
The semantic type of prediction represented by this detection. |
tags |
List[PredictedTag]
|
The tags predicted by the model for the detection. |
Attributes#
detection_score = 1
class-attribute
instance-attribute
#
The score of the detection.
id = Field(default_factory=uuid4)
class-attribute
instance-attribute
#
The unique ID of the detection
location = None
class-attribute
instance-attribute
#
The location of the detection in the recording.
model_config = ConfigDict(frozen=True)
class-attribute
instance-attribute
#
prediction_type
instance-attribute
#
The semantic type of prediction represented by this detection.
tags = Field(default_factory=list)
class-attribute
instance-attribute
#
The tags predicted by the model for the detection.
Methods:#
validate_score(value)
#
Validate that the score is between 0 and 1.
DeviceInfo
#
Bases: BaseModel
Runtime information about the current device.
This object is intentionally small and currently only exposes the device identifier used in filename templates and heartbeat-style messages.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
str
|
Unique identifier for the current device, if available. |
EventDetection
#
Bases: Detection
Detection for a region that contains exactly one target sound event.
Use this when the detected region is intended to describe one single sound event.
Methods:
| Name | Description |
|---|---|
validate_score |
Validate that the score is between 0 and 1. |
Attributes:
| Name | Type | Description |
|---|---|---|
detection_score |
float
|
The score of the detection. |
id |
UUID
|
The unique ID of the detection |
location |
Optional[BoundingBox]
|
The location of the detection in the recording. |
model_config |
|
|
prediction_type |
PredictionType
|
|
tags |
List[PredictedTag]
|
The tags predicted by the model for the detection. |
Attributes#
detection_score = 1
class-attribute
instance-attribute
#
The score of the detection.
id = Field(default_factory=uuid4)
class-attribute
instance-attribute
#
The unique ID of the detection
location = None
class-attribute
instance-attribute
#
The location of the detection in the recording.
model_config = ConfigDict(frozen=True)
class-attribute
instance-attribute
#
prediction_type = Field(default=(PredictionType.EVENT), init=False, repr=False)
class-attribute
instance-attribute
#
tags = Field(default_factory=list)
class-attribute
instance-attribute
#
The tags predicted by the model for the detection.
Methods:#
validate_score(value)
#
Validate that the score is between 0 and 1.
Message
#
Bases: BaseModel
The message to be sent to the remote server.
Attributes:
| Name | Type | Description |
|---|---|---|
content |
Union[str, bytes]
|
The message to be sent. Usually JSON text, but may be raw bytes. |
created_on |
AwareDatetime
|
The datetime when the message was created. |
id |
UUID
|
The unique ID of the message. |
Attributes#
content
instance-attribute
#
The message to be sent. Usually JSON text, but may be raw bytes.
created_on = Field(default_factory=utc_now)
class-attribute
instance-attribute
#
The datetime when the message was created.
id = Field(default_factory=uuid4)
class-attribute
instance-attribute
#
The unique ID of the message.
Metric
#
Bases: BaseModel
A metric is a single value with a name and unit.
Used to report the status of a system or model.
Attributes:
| Name | Type | Description |
|---|---|---|
captured_on |
datetime
|
The date and time the metric was captured. |
name |
str
|
The name of the metric. |
unit |
str
|
The unit of the metric. |
value |
float
|
The value of the metric. |
ModelOutput
#
Bases: BaseModel
The output of a model.
Attributes:
| Name | Type | Description |
|---|---|---|
created_on |
AwareDatetime
|
The datetime when the model output was created. |
detections |
Sequence[Detection]
|
List of predicted sound events in the recording. |
id |
UUID
|
The unique ID of the model output. |
model_config |
|
|
name_model |
str
|
The name of the model that produced the output. |
recording |
Recording
|
The recording that was used as input to the model. |
Attributes#
created_on = Field(default_factory=utc_now)
class-attribute
instance-attribute
#
The datetime when the model output was created.
detections = Field(default_factory=list)
class-attribute
instance-attribute
#
List of predicted sound events in the recording.
id = Field(default_factory=uuid4)
class-attribute
instance-attribute
#
The unique ID of the model output.
model_config = ConfigDict(frozen=True)
class-attribute
instance-attribute
#
name_model
instance-attribute
#
The name of the model that produced the output.
recording
instance-attribute
#
The recording that was used as input to the model.
ModelOutputInfo
#
Bases: BaseModel
Lightweight model-output information for management-style queries.
Attributes:
| Name | Type | Description |
|---|---|---|
created_on |
AwareDatetime
|
The datetime when the model output was created. |
id |
UUID
|
The unique ID of the model output. |
name_model |
str
|
The name of the model that produced the output. |
Attributes#
created_on = Field(default_factory=utc_now)
class-attribute
instance-attribute
#
The datetime when the model output was created.
id = Field(default_factory=uuid4)
class-attribute
instance-attribute
#
The unique ID of the model output.
name_model
instance-attribute
#
The name of the model that produced the output.
PredictedTag(tag, confidence_score=1)
dataclass
#
A PredictedTag is a label predicted by a model.
It consists of a key, a value and a score.
Attributes:
| Name | Type | Description |
|---|---|---|
confidence_score |
float
|
The confidence score of the predicted tag. |
tag |
Tag
|
The tag predicted by the model. |
PredictionType
#
Bases: str, Enum
Describe what kind of sound pattern a detection refers to.
This helps explain how to interpret the area covered by a detection. A detection may refer to a general presence of sound in a region, one whole sequence of related sounds, or one single sound event.
Attributes:
| Name | Type | Description |
|---|---|---|
EVENT |
Exactly one single target sound event is present in the detected region. |
|
PRESENCE |
One or more target sounds are present in the detected region. |
|
SEQUENCE |
Exactly one sequence of related sounds is present in the detected region. |
Attributes#
EVENT = 'event'
class-attribute
instance-attribute
#
Exactly one single target sound event is present in the detected region.
PRESENCE = 'presence'
class-attribute
instance-attribute
#
One or more target sounds are present in the detected region.
SEQUENCE = 'sequence'
class-attribute
instance-attribute
#
Exactly one sequence of related sounds is present in the detected region.
PresenceDetection
#
Bases: Detection
Detection for a region where one or more target sounds are present.
This is the most general detection type. It is useful for full-recording, clip-level, or bounding-box predictions when the detected region may contain one or more sound events.
Methods:
| Name | Description |
|---|---|
validate_score |
Validate that the score is between 0 and 1. |
Attributes:
| Name | Type | Description |
|---|---|---|
detection_score |
float
|
The score of the detection. |
id |
UUID
|
The unique ID of the detection |
location |
Optional[BoundingBox]
|
The location of the detection in the recording. |
model_config |
|
|
prediction_type |
PredictionType
|
|
tags |
List[PredictedTag]
|
The tags predicted by the model for the detection. |
Attributes#
detection_score = 1
class-attribute
instance-attribute
#
The score of the detection.
id = Field(default_factory=uuid4)
class-attribute
instance-attribute
#
The unique ID of the detection
location = None
class-attribute
instance-attribute
#
The location of the detection in the recording.
model_config = ConfigDict(frozen=True)
class-attribute
instance-attribute
#
prediction_type = Field(default=(PredictionType.PRESENCE), init=False, repr=False)
class-attribute
instance-attribute
#
tags = Field(default_factory=list)
class-attribute
instance-attribute
#
The tags predicted by the model for the detection.
Methods:#
validate_score(value)
#
Validate that the score is between 0 and 1.
Recording
#
Bases: BaseModel
A Recording is a single audio file recorded from the microphone.
Methods:
| Name | Description |
|---|---|
validate_audio_channels |
Validate that the number of audio_channels is greater than 1. |
validate_duration |
Validate that the duration is greater than 0. |
validate_samplerate |
Validate that the samplerate is greater than 0. |
Attributes:
| Name | Type | Description |
|---|---|---|
audio_channels |
Optional[int]
|
The number of audio_channels in the recording. |
created_on |
AwareDatetime
|
The datetime when the recording was made |
deployment |
Deployment
|
The deployment that the recording belongs to |
duration |
float
|
The duration of the recording in seconds |
id |
UUID
|
The unique ID of the recording |
path |
Optional[Path]
|
The path to the audio file in the local filesystem |
samplerate |
int
|
The samplerate of the recording in Hz |
time_expansion |
float
|
Factor by which the recording's time scale is multiplied. |
Attributes#
audio_channels = Field(default=1, repr=False)
class-attribute
instance-attribute
#
The number of audio_channels in the recording.
created_on = Field(default_factory=utc_now, repr=False)
class-attribute
instance-attribute
#
The datetime when the recording was made
deployment = Field(repr=False)
class-attribute
instance-attribute
#
The deployment that the recording belongs to
duration = Field(repr=False)
class-attribute
instance-attribute
#
The duration of the recording in seconds
id = Field(default_factory=uuid4, repr=True)
class-attribute
instance-attribute
#
The unique ID of the recording
path = Field(None, repr=True)
class-attribute
instance-attribute
#
The path to the audio file in the local filesystem
samplerate = Field(repr=False)
class-attribute
instance-attribute
#
The samplerate of the recording in Hz
time_expansion = Field(default=1, repr=False, gt=0)
class-attribute
instance-attribute
#
Factor by which the recording's time scale is multiplied.
Values > 1.0 indicate time expansion (slowing down playback), while values between 0.0 and 1.0 indicate time compression (speeding up playback).
Methods:#
validate_audio_channels(value)
#
Validate that the number of audio_channels is greater than 1.
validate_duration(value)
#
Validate that the duration is greater than 0.
validate_samplerate(value)
#
Validate that the samplerate is greater than 0.
Response
#
Bases: BaseModel
The response from sending a message.
Attributes:
| Name | Type | Description |
|---|---|---|
content |
Optional[str]
|
The content of the response. |
message |
Message
|
The message that was sent. |
received_on |
AwareDatetime
|
The datetime the message was received. |
status |
ResponseStatus
|
The status of the message. |
Attributes#
content = None
class-attribute
instance-attribute
#
The content of the response.
message
instance-attribute
#
The message that was sent.
received_on = Field(default_factory=utc_now)
class-attribute
instance-attribute
#
The datetime the message was received.
status
instance-attribute
#
The status of the message.
ResponseStatus
#
Bases: IntEnum
The status of a message.
Attributes:
| Name | Type | Description |
|---|---|---|
ERROR |
The message was sent, but there was an error. |
|
FAILED |
The message failed to send. |
|
SUCCESS |
The message was received successfully. |
|
TIMEOUT |
The message timed out. |
Attributes#
ERROR = 2
class-attribute
instance-attribute
#
The message was sent, but there was an error.
FAILED = 1
class-attribute
instance-attribute
#
The message failed to send.
SUCCESS = 0
class-attribute
instance-attribute
#
The message was received successfully.
TIMEOUT = 3
class-attribute
instance-attribute
#
The message timed out.
SequenceDetection
#
Bases: Detection
Detection for a region that contains exactly one sequence of sounds.
Use this when the detected region refers to one meaningful group of related sounds rather than a single event.
Methods:
| Name | Description |
|---|---|
validate_score |
Validate that the score is between 0 and 1. |
Attributes:
| Name | Type | Description |
|---|---|---|
detection_score |
float
|
The score of the detection. |
id |
UUID
|
The unique ID of the detection |
location |
Optional[BoundingBox]
|
The location of the detection in the recording. |
model_config |
|
|
prediction_type |
PredictionType
|
|
tags |
List[PredictedTag]
|
The tags predicted by the model for the detection. |
Attributes#
detection_score = 1
class-attribute
instance-attribute
#
The score of the detection.
id = Field(default_factory=uuid4)
class-attribute
instance-attribute
#
The unique ID of the detection
location = None
class-attribute
instance-attribute
#
The location of the detection in the recording.
model_config = ConfigDict(frozen=True)
class-attribute
instance-attribute
#
prediction_type = Field(default=(PredictionType.SEQUENCE), init=False, repr=False)
class-attribute
instance-attribute
#
tags = Field(default_factory=list)
class-attribute
instance-attribute
#
The tags predicted by the model for the detection.
Methods:#
validate_score(value)
#
Validate that the score is between 0 and 1.