Getting Started

Cochl.Sense Cloud API is the only publicly available solution for machine listening. It supports prerecorded audio inputs and multiple formats such as MP3, WAV, and FLAC, allowing you to start analyzing your audio right away.

1. Set Up Python Environment

Cochl.Sense Cloud API can be easily integrated into any Python application using the Cochl library. The library supports Python versions 3.9 or higher. Please make sure you’re using a compatible version of Python. First, create a Python virtual environment.

python3 -m venv venv
. venv/bin/activate
pip install --upgrade pip
pip install --upgrade cochl
git clone https://github.com/cochlearai/cochl-sense-py.git
cd cochl-sense-py/samples

python3 -m venv venv
. venv/bin/activate
pip install --upgrade pip
pip install --upgrade cochl
git clone https://github.com/cochlearai/cochl-sense-py.git
cd cochl-sense-py/samples

python -m venv venv
.\venv\Scripts\activate
pip install --upgrade pip
pip install --upgrade cochl
git clone https://github.com/cochlearai/cochl-sense-py.git
cd cochl-sense-py/samples

2. Get Your Project Key

To use the solution, create a project in the dashboard and copy the project key. For details, see the guide here.

3. Run the Example

This simple setup is enough to upload your file. Please input your retrieved API project key into “YOUR_API_PROJECT_KEY”.

import cochl.sense as sense
from cochl.sense import Result

api_config = sense.APIConfigFromJson('./config.json')
client = sense.Client(
    'YOUR_API_PROJECT_KEY',
    api_config=api_config,
)
result: Result = client.predict('your_file.wav')

print(result.events.to_dict(api_config))  # Return the event result as a dictionary.
# print(result.events_summarized(api_config))  # Return the event result in a simplified form.

You can adjust custom settings in the config.json file. For more details, see the Advanced configurations section.

{
  "sensitivity_control": {
    "default_sensitivity": 0,
    "tag_sensitivity": {
    }
  },
  "result_summary": {
    "default_interval_margin": 0,
    "tag_interval_margin": {
    }
  },
  "tag_filter": {
    "enabled_tags": []
  }
}

4. Check Usage

You can review your usage on the Cochl.Sense Dashboard.

5. Additional Notes

(1) Convert to Supported File Formats (WAV, MP3, OGG)

Pydub is an easy way to convert audio files into supported formats (WAV, MP3, and OGG). First, install Pydub by following the instructions in this link. Then, write a Python script to convert your file into a supported format, as shown 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.