Skip to main content

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 two API classes; pick the one that matches your task.

Class Use for Auth key
IntegratedApi All-in-one analysis: Sound Event Detection + Speech Analysis + Audio Insights in one request. Enable only the services you need. Project key (X-Api-Key)
SpeakerProfileApi Register / list / recognize / delete voice profiles used by Speech Analysis. Organization key (X-Org-Key)

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

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:

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.

sound_event_detection speech_analysis audio_insights Result
✅ ❌ ❌ OK — SED only
❌ ✅ ❌ OK — Speech Analysis only
✅ ✅ ❌ OK — SED + Speech Analysis
✅ ✅ ✅ OK — full stack (Dashboard default)
❌ ❌ ❌ 400 — no services selected
❌ ❌ ✅ 400 — audio_insights requires both SED and Speech Analysis
✅ ❌ ✅ 400 — audio_insights requires speech_analysis
❌ ✅ ✅ 400 — audio_insights requires sound_event_detection

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.

Metadata

Release files for cochl 2.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cochl 2.0.3
File Size Uploaded Provenance Actions
cochl-2.0.3.tar.gz 10.7 kB Without provenance Details for cochl-2.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cochl 2.0.3
File Interpreter ABI Platform Actions
cochl-2.0.3-py3-none-any.whl Python 3 none any Details for cochl-2.0.3-py3-none-any.whl

Total release size: 24.1 kB

Release files / cochl-2.0.3.tar.gz

Download URL cochl-2.0.3.tar.gz
Size 10.7 kB
Tags Source
SHA-256 checksum
How to use checksums
b786ab8c1941519bc6e3c6a98304afa5060686b2ffa81e7d9065e8ea2b65ff87
BLAKE2b-256 checksum
How to use checksums
052c809386daf07d54c8efc35f912732a53668da11e705f410142f2a211017ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.0

Release files / cochl-2.0.3-py3-none-any.whl

Download URL cochl-2.0.3-py3-none-any.whl
Size 13.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0933ede159c10489a79d19b97216228cddcbeead1976efc5cd3b5a96ab7dc570
BLAKE2b-256 checksum
How to use checksums
355f03cdb20033962cbce03b434e9d5c83df93f41867527e3ebcd225e66f1e46
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.0

Security for cochl 2.0.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page