cochl 0.2.11

Cochl Sense

cochl-sense-py

cochl-sense-py is a Python client library providing easy integration of Cochl.Sense API into any Python application. You can upload a file (MP3, WAV, OGG) or raw PCM audio stream.

Installation

cochl-sense-py can be installed and used in Python 3.8+.

pip install --upgrade cochl

Usage

This simple setup is enough to input your file. API project key can be retrieved from Cochl Dashboard.

import cochl.sense as sense

client = sense.Client("YOUR_API_PROJECT_KEY")

results = client.predict("your_file.wav")
print(results.to_dict())  # get results as a dict

You can adjust the custom settings like below. For more details please refer to Advanced Cconfigurations.

import cochl.sense as sense

api_config = sense.APIConfig(
    sensitivity=sense.SensitivityConfig(
        default=sense.SensitivityScale.LOW,
        by_tags={
            "Baby_cry": sense.SensitivityScale.VERY_LOW,
            "Gunshot":  sense.SensitivityScale.HIGH,
        },
    ),
)

client = sense.Client(
    "YOUR_API_PROJECT_KEY",
    api_config=api_config,
)

results = client.predict("your_file.wav")
print(results.to_dict())  # get results as a dict

The file prediction result can be displayed in a summarized format. More details at Summarized Result.

# print(results.to_dict())  # get results as a dict

print(results.to_summarized_result(
    interval_margin=2,
    by_tags={"Baby_cry": 5, "Gunshot": 3}
))  # get results in a simplified format

# At 0.0-1.0s, [Baby_cry] was detected

Cochl.Sense API supports three file formats: MP3, WAV, OGG.
If a file is not in a supported format, it has to be manually converted. More details here.

Advanced Configurations

Sensitivity

Detection sensitivity can be adjusted for all tags or each tag individually.
If you feel that tags are not detected well enough, increase sensitivities. If there are too many false detections, lower sensitivities.

The sensitivity is adjusted with SensitivityScale Enum.

• VERY_HIGH
• HIGH
• MEDIUM (default)
• LOW
• VERY_LOW

import cochl.sense as sense

api_config = sense.APIConfig(
    sensitivity=sense.SensitivityConfig(
        # default sensitivity applied to all tags not specified in `by_tags`
        default=sense.SensitivityScale.LOW,
        by_tags={
            "Baby_cry": sense.SensitivityScale.VERY_LOW,
            "Gunshot":  sense.SensitivityScale.HIGH,
        },
    ),
)
client = sense.Client(
    "YOUR_API_PROJECT_KEY",
    api_config=api_config,
)

Other notes

Convert to supported file formats (WAV, MP3, OGG)

Pydub is one of the easy ways to convert audio file into a supported format (WAV, MP3, OGG).

First install Pydub refering to this link.
Then write a Python script converting your file into a supported format like below.

from pydub import AudioSegment

mp4_version = AudioSegment.from_file("sample.mp4", "mp4")
mp4_version.export("sample.mp3", format="mp3")

For more details of Pydub, please refer to this link.

Summarzied Result

You can summarize the file prediction result by aggregating consecutive windows, returning the time and length of the detected tag.
The 'interval margin' is a parameter that treats the unrecognized window between tags as part of the recognized ones and it affects all sound tags. If you want to specify a different interval margin for specific sound tags, you can use the 'by_tags' option.

print(results.to_summarized_result(
    interval_margin=2,
    by_tags={"Baby_cry": 5, "Gunshot": 3}
))

# At 0.0-1.0s, [Baby_cry] was detected

Links

Documentation: https://docs.cochl.ai/sense/api/