Getting started

Every API access is managed with an API key. If you are a first time user, visit to create an account. Once you have an account, you can create projects. Your API keys are unique and correspond to one of your projects. If you have already set up the Cochl.Sense python API, you can skip to step 7.

1. Requirements

This tutorial is available on the following systems:

  • Python 3.6–3.8
  • Python 3.6–3.8
  • Python 3.6

2. Install Dependencies

  • Open Terminal.
  • Enter the commands below to install Homebrew. (It takes a few minutes if there are no command line tools for Xcode.)
/usr/bin/ruby -e "$(curl -fsSL"
export PATH="/usr/local/opt/python/libexec/bin:$PATH"
brew update
brew install python
  • Open Terminal.
  • Enter the command below to install Python, pip package manager, and venv..
sudo apt update
sudo apt install python3-dev python3-pip python3-venv git

3. Create a Virtual Environment

Create a Python virtual environement

  • Make a temporary folder Cochl_sense_API in the Desktop directory for the tutorial.
  • Create a virtual environment by making a ./venv directory.
  • Activate the virtual environment.
  • Upgrade pip in the virtual environment.

mkdir ~/Desktop/Cochl_sense_API/
python3 -m venv --system-site-packages ~/Desktop/Cochl_sense_API/venv
source ~/Desktop/Cochl_sense_API/venv/bin/activate
pip install --upgrade pip
mkdir ~/Desktop/Cochl_sense_API/
python3 -m venv --system-site-packages ~/Desktop/Cochl_sense_API/venv
source ~/Desktop/Cochl_sense_API/venv/bin/activate
pip install --upgrade pip
  • Open Command Prompt (Press Windows+R, type “cmd”, and then click “OK”).
mkdir %HOMEPATH%\Desktop\Cochl_sense_API\
python -m venv --system-site-packages %HOMEPATH%\Desktop\Cochl_sense_API\venv
pip install --upgrade pip

4. Install PortAudio

If you want to send audio via your microphone, you will need to have PortAudio installed

brew install portaudio
sudo apt install portaudio19-dev

With Python 3.6 or older, there is no need to install PortAudio separately.

5. Install Cochl.Sense

There are two ways to install Cochl.Sense from Github – one is to download it manually and the other is to use git clone.

  • Download quickstart

git clone ~/Desktop/Cochl_sense_API/sense-python-master
git clone ~/Desktop/Cochl_sense_API/sense-python-master
git clone  %HOMEPATH%\Desktop\Cochl_sense_API\sense-python-master
Install Cochl.Sense1
  • Extract the zip file(“sense-python-master”) into the temporary folder(“Cochl_sense_API”) in the Desktop directory.
Install Cochl.Sense2

  • Install Python dependencies

pip install -r ~/Desktop/Cochl_sense_API/sense-python-master/examples/requirements.txt
pip install -r ~/Desktop/Cochl_sense_API/sense-python-master/examples/requirements.txt
pip install -r %HOMEPATH%\Desktop\Cochl_sense_API\sense-python-master\examples\requirements.txt

6. Get and API Key


  • Enter the link( and log in to the dashboard. If you don’t have an ID, sign up as a member to use our service.
  • Create a new API project. Enter your project information including your project name, type of platform (should be API), and type of service. In this tutorial, we will test the “Human Interaction” service.
  • Confirm that the project has been created and copy the API key by clicking it.

Get API2

  • Set your API key as the environment variable. Type the below command in Terminal or Command Prompt. You need to change %YOUR_API_KEY% with your own key copied from the dashboard.


7. Inference (file, stream)

In order to test the example program, make sure you are in the virtual environment. (venv) should be at the beginning of the command line. If there is no (venv), you need to activate virtualenv with the command below.

source ~/Desktop/Cochl_sense_API/venv/bin/activate
cd ~/Desktop/Cochl_sense_API/sense-python-master/examples
source ~/Desktop/Cochl_sense_API/venv/bin/activate
cd ~/Desktop/Cochl_sense_API/sense-python-master/examples
cd %HOMEPATH%\Desktop\Cochl_sense_API\sense-python-master\examples

Now, you can test both file inference and stream inference. We will test the “Human Interaction” service for this tutorial. “Human Interaction” can detect the following: ‘Clap’, ‘Finger_snap’, ‘Knock’, ‘Whisper’, and ‘Whistling’.


Type the command below.


Then, you will see the results.

  {'Whistling': [(0.0, 2.0)], 'Others': [(1.5, 2.5), (3.0, 4.0), (4.5, 6.0), (6.5, 8.0)],
  'Finger_snap': [(2.0, 5.0)], 'Clap': [(5.5, 7.0)], 'Knock': [(7.5, 9.0)]}

The JSON result indicates there were ‘Whistling’ sounds between 0 and 2 seconds, ‘Finger_snap’ sounds between 2 and 5 seconds, ‘Clap’ sounds between 5.5 and 7 seconds, and ‘Knock’ sounds between 7.5 and 9 seconds. Sound events that are not supported by “Human Interaction” and periods of silence are classified as ‘Others’.



Before you try stream inference, we highly recommend that you test your microphone settings (Ubuntu, macOS, Windows). If your microphone settings are not properly set, the program may operate incorrectly.


When you stream inference, you can see the results in real-time as demonstrated below. It will last for 120 seconds, but you can stop the stream by pressing Ctrl + C.

{'Others': [(5.0, 6.0)]}
{"Finger_snap': [(5.5, 6.5)]}
{'Others': ((6.0, 7.0)]}
{"Finger_snap': [(6.5, 7.5)]}
{'Others': [17.0, 8.0)]} 
{'Others': [(7.5, 8.5)]}
{"Finger_snap': [(8., 9.0)]} 
{'Others': [(8.5, 9.5)]}
{ 'Others': [(9.8, 10.0)]} 
{'Clap': [(9.5, 10.5)]} 
{'Others': [(10.8, 11.6)]} 
{'Others': [(10.5, 11.5)]} 
{'Others': ((11.0, 12.0)]} 
{"Knock': [(11.5, 12.5)]}
{'Others': [(12.0, 13.0)]} 

8. Check Usage

After using file/stream inference several times, you can review your usage in the dashboard, check your amount of consumed AU (analyzed unit), and view your cost.