Cobra

Made in Vancouver, Canada by Picovoice

Cobra is a highly-accurate and lightweight voice activity detection (VAD) engine.

Table of Contents

• Cobra
  • Table of Contents
  • Demos
    • Python
    • C
    • Android
    • iOS
    • Web
    • Rust
  • SDKs
    • Python
    • C
    • Android
    • iOS
    • Web
    • Rust
  • Releases

Demos

Python Demos

Install the demo package:

sudo pip3 install pvcobrademo

With a working microphone connected to your device run the following in the terminal:

cobra_demo_mic --access_key ${AccessKey}

Replace ${AccessKey} with your AccessKey obtained from Picovoice Console. Cobra starts processing the audio input from the microphone in realtime and outputs to the terminal when it detects any voice activities.

For more information about the Python demos go to demo/python.

C Demos

Build the demo:

cmake -S demo/c/ -B demo/c/build && cmake --build demo/c/build --target cobra_demo_mic

To list the available audio input devices:

./demo/c/build/cobra_demo_mic -s

To run the demo:

./demo/c/build/cobra_demo_mic -l ${LIBRARY_PATH} -a ${ACCESS_KEY} -d ${AUDIO_DEVICE_INDEX}

Replace ${LIBRARY_PATH} with path to appropriate library available under lib, Replace ${ACCESS_KEY} with AccessKey obtained from Picovoice Console, and ${INPUT_AUDIO_DEVICE} with the index of your microphone device.

For more information about C demos go to demo/c.

Android Demos

Using Android Studio, open demo/android/Activity as an Android project and then run the application. Replace String ACCESS_KEY = "..." inside MainActivity.java with your AccessKey generated by Picovoice Console.

For more information about Android demos go to demo/android.

iOS demos

Run the following from this directory to install the Cobra-iOS CocoaPod:

pod install

Replace let ACCESS_KEY = "..." inside ViewModel.swift with yours obtained from Picovoice Console.

Then, using Xcode, open the generated CobraDemo.xcworkspace and run the application. Press the start button and start talking. The background will change colour while you're talking.

For more information about iOS demos go to demo/ios.

Web Demos

From demo/web run the following in the terminal:

yarn
yarn start

(or)

npm install
npm run start

Open http://localhost:5000 in your browser to try the demo.

Rust Demos

From demo/rust/micdemo build and run the demo:

cargo run --release -- --access_key ${ACCESS_KEY}

For more information about Rust demos go to demo/rust.

SDKs

Python

Install the Python SDK:

pip3 install pvcobra

The SDK exposes a factory method to create instances of the engine:

import pvcobra

handle = pvcobra.create(access_key=${AccessKey})

where ${AccessKey} is an AccessKey which should be obtained from Picovoice Console. When initialized, valid sample rate can be obtained using handle.sample_rate. The required frame length (number of audio samples in an input array) is handle.frame_length. The object can be used to monitor incoming audio as follows:

def get_next_audio_frame():
    pass

while True:
    voice_probability = handle.process(get_next_audio_frame())

Finally, when done be sure to explicitly release the resources using handle.delete().

C

include/pv_cobra.h header file contains relevant information. Build an instance of the object:

    pv_cobra_t *handle = NULL;
    pv_status_t status = pv_cobra_init(${ACCESS_KEY}, &handle);
    if (status != PV_STATUS_SUCCESS) {
        // error handling logic
    }

Replace ${ACCESS_KEY} with the AccessKey obtained from Picovoice Console. Now the handle can be used to monitor incoming audio stream. Cobra accepts single channel, 16-bit linearly-encoded PCM audio. The sample rate can be retrieved using pv_sample_rate(). Finally, Cobra accepts input audio in consecutive chunks (aka frames) the length of each frame can be retrieved using pv_cobra_frame_length().

extern const int16_t *get_next_audio_frame(void);

while (true) {
    const int16_t *pcm = get_next_audio_frame();
    float is_voiced = 0.f;
    const pv_status_t status = pv_cobra_process(handle, pcm, &is_voiced);
    if (status != PV_STATUS_SUCCESS) {
        // error handling logic
    }
}

Finally, when done be sure to release the acquired resources:

pv_cobra_delete(handle);

Android

Create an instance of the engine

import ai.picovoice.cobra.Cobra;
import ai.picovoice.cobra.CobraException;

String accessKey = // .. AccessKey provided by Picovoice Console (https://console.picovoice.ai/)
try {
    handle = new Cobra(accessKey);
} catch (CobraException e) {
    // handle error
}

When initialized, valid sample rate can be obtained using handle.getSampleRate(). The required frame length (number of audio samples in an input array) is handle.getFrameLength(). The object can be used to monitor incoming audio as follows:

short[] getNextAudioFrame(){

while(true) {
    try {
        final float voiceProbability = handle.process(getNextAudioFrame());
    } catch (CobraException e) { }
}

Finally, when done be sure to explicitly release the resources using handle.delete().

iOS

To import the Cobra iOS binding into your project, add the following line to your Podfile and run pod install:

pod 'Cobra-iOS'

Create an instance of the engine

import Cobra

let accessKey : String = // .. AccessKey provided by Picovoice Console (https://console.picovoice.ai/)
do {
    handle = try Cobra(accessKey: accessKey)
} catch { }

func getNextAudioFrame() -> [Int16] {
    // .. get audioFrame
    return audioFrame;
}

while true {
    do {
        let voiceProbability = try handle.process(getNextAudioFrame())
    } catch { }
}

Finally, when done be sure to explicitly release the resources using handle.delete().

Web

Cobra is available on modern web browsers (i.e., not Internet Explorer) via WebAssembly. Cobra is provided pre-packaged as a Web Worker to allow it to perform processing off the main thread.

The Cobra package @picovoice/cobra-web-worker can be used with the @picovoice/web-voice-processor. Microphone audio is handled via the Web Audio API and is abstracted by the WebVoiceProcessor, which also handles down-sampling to the correct format.

Vanilla JavaScript and HTML (CDN Script Tag)

<!DOCTYPE html>
<html lang="en">
  <head>
    <script src="https://unpkg.com/@picovoice/cobra-web-worker/dist/iife/index.js"></script>
    <script src="https://unpkg.com/@picovoice/web-voice-processor/dist/iife/index.js"></script>
    <script type="application/javascript">
      function cobraCallback(voiceProbability) {
        const threshold = 0.8;
        if voiceProbability >= threshold {
          const timestamp = new Date();
          console.log("Voice detected with probability of " +
            voiceProbability.toFixed(2) +
            " at " +
            timestamp.toString()
          );
        }
      }

      async function startCobra() {
        const accessKey = // AccessKey string provided by Picovoice Console (picovoice.ai/console/)
        const cobraWorker = await CobraWorkerFactory.create(
          accessKey,
          cobraCallback
        );

        console.log("Cobra worker ready!");

        console.log("WebVoiceProcessor initializing. Microphone permissions requested ...");

        try {
          let webVp = await window.WebVoiceProcessor.WebVoiceProcessor.init({
            engines: [cobraWorker],
          });
          console.log("WebVoiceProcessor ready and listening!");
        } catch (e) {
          console.log("WebVoiceProcessor failed to initialize: " + e);
        }
      }

      document.addEventListener("DOMContentLoaded", function () {
        startCobra();
      });
    </script>
  </head>
  <body></body>
</html>

Vanilla JavaScript and HTML (ES Modules)

yarn add @picovoice/cobra-web-worker @picovoice/web-voice-processor

(or)

npm install @picovoice/cobra-web-worker @picovoice/web-voice-processor

import { WebVoiceProcessor } from "@picovoice/web-voice-processor"
import { CobraWorkerFactory } from "@picovoice/cobra-web-worker";

function cobraCallback(voiceProbability) {
  const threshold = 0.8;
  if voiceProbability >= threshold {
    const timestamp = new Date();
    console.log("Voice detected with probability of " +
      voiceProbability.toFixed(2) +
      " at " +
      timestamp.toString()
    );
  }
}

async function startCobra() {
  const accessKey = //AccessKey string provided by Picovoice Console (picovoice.ai/console/)
  const cobraWorker = await CobraWorkerFactory.create(
      accessKey,
      cobraCallback
  );

  const webVp =
      await WebVoiceProcessor.init({
        engines: [cobraWorker],
        start: true,
      });
}

startCobra()

Rust

Create an instance of the engine and detect voice activity:

use cobra::Cobra;

let cobra = Cobra::new("${ACCESS_KEY}");

fn next_audio_frame() -> Vec<i16> {
    // get audio frame
}

loop {
    if let Ok(voice_probability) = cobra.process(&next_audio_frame()) {
      // ...
    }
}

Releases

v1.1.0 January 21st, 2022

• Improved types for web binding
• Various bug fixes and improvments

v1.0.0 October 8th, 2021

• Initial release.