cochl

cochl is the official Python client library for the Cochl.Sense Cloud API. Use it to detect sound events, transcribe and identify speakers, and summarize what's happening in an audio file, all from Python.

For end-user product documentation see docs.cochl.ai.

Installation

Supported on Python 3.10+.

pip install --upgrade cochl

What's in the library

The library exposes three API classes; pick the one that matches your task.

Project keys are per-project (Dashboard → Projects → your project → Settings). Organization keys apply across the whole organization (Dashboard → Organization).

Project keys do not expire — rotate them by regenerating from the project's Settings tab.

Samples

Working scripts for each API class live under samples/. Replace the placeholder key and audio file path, then run with python samples/<file>.py.

samples/
├── sample_audio_insights.py        # IntegratedApi — audio_insights=True
├── sample_sound_event_detection.py # IntegratedApi — sound_event_detection=True
├── sample_speech_analysis.py       # IntegratedApi — speech_analysis=True
├── sample_speaker_profile_api.py   # SpeakerProfileApi — register / list / recognize / delete
└── legacy/
    ├── sample.py                   # Legacy Client (v1.x response shape)
    └── config.json                 # Sensitivity / result_summary / tag_filter knobs for Client

Quick start — IntegratedApi

from cochl.sense import IntegratedApi, IntegratedApiOptions

api = IntegratedApi('YOUR_API_PROJECT_KEY')

job = api.analyze_file(
    'your_file.wav',
    IntegratedApiOptions(
        sound_event_detection=True,
        speech_analysis=True,
        audio_insights=True,
    ),
)

# Block until the job finishes, then return the final result dict.
result = api.get_completed_result(job['job_id'])
print(result)

result is a dict with one top-level key per enabled analysis, plus metadata:

• sound_event_detection — status, and results[] on success. Each entry is a 2 s window advancing in 1 s steps (00:00–00:02, 00:01–00:03, …) carrying classes[] (each {class, confidence, id}), start_time / end_time (MM:SS.ss), start_time_sec / end_time_sec, and an id.
• speech_analysis — status, and results[] on success: speaker-turn segments with transcript, speaker (the diarization label, SPEAKER_00, SPEAKER_01, …), speaker_name, speaker_score, start_time / end_time, start_time_sec / end_time_sec, and item_ids. speaker_name is always present: it holds the registered Speaker Profile's name when one matches, and Unknown 0, Unknown 1, … otherwise, in which case speaker_score is -1.0.
• audio_insights — status, plus result (a single object with contains_speech, detected_language, primary_sound_environment, situation_summary, notable_events[], speech_content_summary, keywords[]) and item_ids mapping each of those fields to an item id.
• metadata — audio.input (filename, format, size_bytes, content_type), audio.processed (sample_rate_hz, channels, encoding, resampled, downmixed), and warnings[].

Check status per service. A service that fails does not raise — the job still completes with HTTP 200, and the failure shows up as status: 'error' with an error message on that service alone:

sed = result['sound_event_detection']
if sed['status'] != 'success':
    print('SED failed:', sed['error'])
else:
    for chunk in sed['results']:
        print(chunk['start_time'], [c['class'] for c in chunk['classes']])

A single upload is capped at 1 hour of audio.

For schema details and per-feature documentation, see:

• Audio Insights
• Speech Analysis
• Sound Event Detection

IntegratedApi accepts MP3, WAV, FLAC, OGG. Convert other formats first — see Convert to supported file formats below.

Valid service combinations

audio_insights is a summary built on top of the other two analyses, so it can't run on its own — enable it only together with both sound_event_detection and speech_analysis. At least one service must be enabled. Invalid combinations come back as 400.

Speaker Profiles

Register voices ahead of time so IntegratedApi's Speech Analysis can name them (instead of generic SPEAKER_00 / SPEAKER_01).

from cochl.sense import SpeakerProfileApi

api = SpeakerProfileApi('YOUR_ORGANIZATION_KEY')

# Register a profile from an audio sample.
api.add_new_voice('Anna_Kim', 'anna_sample.wav')

# List every profile registered under this organization.
print(api.list_all_speakers())

# Match speakers in a separate file (uses the registered profiles).
print(api.recognize('meeting.wav'))

# Delete a profile.
api.remove('Anna_Kim')

Notes:

• Each add_new_voice / recognize upload is capped at 10 MB per file.
• SpeakerProfileApi uses the organization key (X-Org-Key), not a project key.

See Custom Sound: Speaker Profile for the full registration flow.

Other notes

Convert to supported file formats

Pydub is one easy way to convert audio into a supported format. Install it per the Pydub installation guide, then:

from pydub import AudioSegment

audio = AudioSegment.from_file('sample.mp4', 'mp4')
audio.export('sample.mp3', format='mp3')

For more on Pydub, see the Pydub repo.

Repo layout

This package is published to PyPI from a private development repository (cochl-sense-py-private) and mirrored to the public cochlearai/cochl-sense-py repo for end-user access. Issues and pull requests should be filed against the public mirror.

Links

• Product documentation: docs.cochl.ai
• Public source mirror: github.com/cochlearai/cochl-sense-py
• Issues: github.com/cochlearai/cochl-sense-py/issues