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.2

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.2
File Size Uploaded Provenance Actions
cochl-2.0.2.tar.gz 11.6 kB Without provenance Details for cochl-2.0.2.tar.gz

Built distribution (wheel)

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

Total release size: 24.0 kB

Release files / cochl-2.0.2.tar.gz

Download URL cochl-2.0.2.tar.gz
Size 11.6 kB
Tags Source
SHA-256 checksum
How to use checksums
2ce5f3e89e5c8d0ae886dcbd2988ed7726be1253f1d7873a5157f5a2cf3a068e
BLAKE2b-256 checksum
How to use checksums
3b1377af26391d3f7ee32e6be21d515bc050aeb9a0e731ca142dcfce2f0a2723
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.2-py3-none-any.whl

Download URL cochl-2.0.2-py3-none-any.whl
Size 12.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9711622a521127f4ca1a59de7f8c9497cc51c0419957bde8fc0bbd2e30b1a00b
BLAKE2b-256 checksum
How to use checksums
63610c8b618aeb44d4719729306301ad28be8ac20afa5a10d7d7fffd13b4f484
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.2

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