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, andresults[]on success. Each entry is a 2 s window advancing in 1 s steps (00:00–00:02,00:01–00:03, …) carryingclasses[](each{class, confidence, id}),start_time/end_time(MM:SS.ss),start_time_sec/end_time_sec, and anid.speech_analysis—status, andresults[]on success: speaker-turn segments withtranscript,speaker(the diarization label,SPEAKER_00,SPEAKER_01, …),speaker_name,speaker_score,start_time/end_time,start_time_sec/end_time_sec, anditem_ids.speaker_nameis always present: it holds the registered Speaker Profile's name when one matches, andUnknown 0,Unknown 1, … otherwise, in which casespeaker_scoreis-1.0.audio_insights—status, plusresult(a single object withcontains_speech,detected_language,primary_sound_environment,situation_summary,notable_events[],speech_content_summary,keywords[]) anditem_idsmapping 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), andwarnings[].
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/recognizeupload is capped at 10 MB per file. SpeakerProfileApiuses 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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.