Prerequisites

Before the DeepTone™ SDK can be used, it must first be initialized. Before you do so, ensure you have your License Key. If you don't, you can request it at support@oto.ai.

Setup

This page will guide you through the process of setting up the DeepTone™ SDK in your project. Select your platform below to get started.

Python

Python

info

Note: Python version >=3.8 and <3.11 is required. The current list of supported operating systems is:

• Linux
• Windows
• macOS - Intel
• macOS - M1

Python installation

If you already have a valid python version installed on your machine or know how to do it, please skip this section and continue with the environment setup

To install a specific python version pyenv can be used.

Mac OS / Linux

To setup pyenv in Mac OS or Linux the pyenv-installer can be used. Follow the installation instructions here or directly use this command to install:

curl https://pyenv.run | bash

This will add pyenv initialisation commands to your shell's "rc" file. Reload you shell to apply the changes:

exec $SHELL

Windows

To install pyenv-win follow the instructions here

Now you are ready to use pyenv to install a specific python version:

pyenv install 3.8.x

where x should be replaced with the latest patch version. Alternatively, you can use

pyenv install --list

to get a list of all available python versions.

Once the python version is installed, you can either set it as your local python version

pyenv local 3.8.x

such that this version of python will only be used in your current directory, or set it as your global python version with

pyenv global 3.8.x

Now you are ready to install the DeepTone™ SDK.

Environment setup

Set up your environment using your preferred Python Environment Manager.

Poetry (recommended)

Create a Poetry project if you don’t have one already, by running:

$ poetry new my-project
$ cd my-project
$ poetry shell

Add the following to your pyproject.toml, to configure Poetry to fetch packages from OTO’s PyPI repository:

[[tool.poetry.source]]
name = "deeptone"
url = "https://sdk.oto.ai/pypi/"
secondary = true

On the same file, change the required python version to match the version required by the SDK:

[tool.poetry.dependencies]
python = ">=3.8,<3.11"

After the repository is configured, run the following to add the dependency to your project:

$ poetry add deeptone

Validate the SDK was correctly installed, by importing it within a Python shell and executing the following commands:

$ poetry run python
Python 3.8.8 (..)
>>> import deeptone
>>> deeptone.__version__
'0.13.0'

Pipenv

Create a Pipenv project if you don’t have one already, by running:

$ mkdir my-project && cd my-project
$ pipenv --python 3.8
$ pipenv lock
$ pipenv shell

Then, and add the following to your Pipfile, to configure Pipenv to fetch packages from OTO’s PyPI repository:

[[source]]
name = "deeptone"
url = "https://sdk.oto.ai/pypi/"
verify_ssl = true

Add the following to your Pipfile's [packages] section:

deeptone = { version = "==0.13.0", index = "deeptone" }

After the repository is configured, run the following to add the dependency to your project:

pipenv install

Validate the SDK was correctly installed, by importing it within a Python shell and executing the following commands:

$ pipenv run python
Python 3.8.6 (..)
>>> import deeptone
>>> deeptone.__version__
'0.13.0'

Conda

Create a Conda project if you don’t have one already, by running:

$ conda create --name my-project python=3.8
$ conda activate my-project

Then, install the DeepTone™ SDK via pip, by running the following:

$ pip install deeptone --extra-index-url https://sdk.oto.ai/pypi/

Validate the SDK was correctly installed, by importing it within a Python shell and executing the following commands:

$ python
Python 3.8.6 (..)
>>> import deeptone
>>> deeptone.__version__
'0.13.0'

pip

To install the DeepTone™ SDK via pip, run the following:

$ pip install deeptone --extra-index-url https://sdk.oto.ai/pypi/

Validate the SDK was correctly installed, by importing it within a Python shell and executing the following commands:

$ python
Python 3.8.6 (..)
>>> import deeptone
>>> deeptone.__version__
'0.13.0'

If the import was successful, congratulations, you are now ready to use DeepTone™! Head to our Usage section to start exploring.

Swift/iOS

Swift

Installation

The recommended approach to use the DeepTone™ SDK in your iOS project is using the CocoaPods package manager as it provides flexible dependency management and dead simple installation.

CocoaPods

Install CocoaPods if not already available:

$ [sudo] gem install cocoapods
$ pod setup

Go to the directory of your Xcode project, and Create and Edit your Podfile and add DeepToneSDK:

$ cd /path/to/MyProject
$ pod init
$ edit Podfile

Podfile

# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'

target 'MyProject' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!

  # Pods for MyProject
  pod 'DeeptoneSDK', '~> 1.4.3'
end

Install into your project:

$ pod install

If CocoaPods did not find any of DeepTone™ SDK dependencies execute this command:

$ pod repo update

Open your project in Xcode from the .xcworkspace file (not the usual project file)

$ open MyProject.xcworkspace

API Reference

Please refer to the documentation for further details on types.

Get Started

To use the DeepTone™ SDK in you iOS project you need to initialize an instance of the main DeepTone™ class and then call the asynchronous start function that validates the license and prepares the models to be used later.

let KEY = "YOUR_LICENSE_KEY"
let filePath = Bundle.main.path(forResource: "YourModel", ofType: "model")
let deeptone = Deeptone(key: KEY, modelPath: filePath!)
 
deeptone.start() { result in
    switch (result) {
    case .Success:
        print("SDK is ready!")
    case .Failure(let error):
        print("Something went wrong! Error: ", error)
    }
}

Make sure you have added the model files to the target that you are running.

Once the SDK is initialized you can process a file:

// Initialize deeptone as showed above first
let audioFile = Bundle.main.path(forResource: "YourAudioFile", ofType: ".m4a")
let data: DeeptoneOutput = try! deeptone.loadAudioFile(filePath: audioFile!)

or tap into the microphone of your device to get real time updates.

// Initialize deeptone as showed above first
var output: DeeptoneOutput?
var isRecording: Bool = false
var deeptoneStream: DeeptoneStream?
let audioEngine = AVAudioEngine()

func startRecording() throws {
    deeptoneStream = try self.deeptone.stream(
            onData: { (data: DeeptoneOutput) in
                output = data
            },
            onSuccess: { (data: DeeptoneOutput) in
                output = data
            },
            onError: { (error: DeeptoneSDKError) in
                debugPrint("Error", error)
            })

    let input = audioEngine.inputNode
    let format = input.inputFormat(forBus: 0)

    input.installTap(onBus: 0, bufferSize: 8192, format: format, block: { (buf, when) in
        deeptoneStream?.write(audioBuffer: buf)
    })

    audioEngine.prepare()
    do {
        try audioEngine.start()
    } catch {
        debugPrint("BOOM!")
    }
}

func stopRecording () {
    deeptoneStream.close()
    self.audioEngine.inputNode.removeTap(onBus: 0)
    self.audioEngine.stop()
    self.audioEngine.reset()
}

Examples

The following Examples will help you getting started with the DeepTone™ SDK in iOS:

• Simple Recording Application

Android

Android

Requirements

• SDK Version >= 23
• Android >= 6.0
• Kotlin Coroutines

Installation

Add the OTO Maven repository to your list of repositories, as well as JCenter and Google for other dependencies.

With Gradle, add to the build.gradle of you main project:

allprojects {
    repositories {
        google()
        jcenter()
        maven {
            url "https://sdk.oto.ai/android-releases"
        }
    }
}

Then add the dependency to your project, with Gradle this looks like:

implementation("com.oto:deeptonesdk:<latest_version>")

Getting Started

First import DeepToneSDK:

import com.oto.deeptonesdk.DeeptoneSDK

// Initialize deeptone with a license key and model from your resources files
val modelFileStream = resources.openRawResource(R.raw.com_oto_deeptonesdk_android)
val deeptoneSDK = DeeptoneSDK(applicationContext, "someKey", modelFileStream)

// Get predictions from file

// Create a suspend function to run as a Kotlin coroutine
suspend fun analyzeFile(audioFileURL: String) {
    withContext(Dispatchers.IO) {
        // DeepToneSDK should be started somewhere else
        deepToneSDK.start()
        val data = deepToneSDK.loadAudioFile(audioFileURL)
        // Do something with the data
    }
}

// Invoke the function with the desired resource
val audioFileURL = "url-to-an-audio-file-publicly-available-on-the-internet"
scope = CoroutineScope(Dispatchers.IO)
scope.launch {
    analyzeFile(audioFileURL)
}

// Get predictions from the microphone
var deeptoneStream: DeeptoneStream? = null
var recorder: AudioRecord? = null

fun startRecording() {
    val bufferSizeInBytes = AudioRecord.getMinBufferSize(
        8000,
        AudioFormat.CHANNEL_IN_MONO,
        AudioFormat.ENCODING_PCM_16BIT
    )

    recorder = AudioRecord.Builder()
        .setAudioSource(MediaRecorder.AudioSource.MIC)
        .setAudioFormat(
            AudioFormat.Builder()
                .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
                .setSampleRate(8000)
                .setChannelMask(AudioFormat.CHANNEL_IN_MONO)
                .build()
        )
        .setBufferSizeInBytes(bufferSizeInBytes)
        .build()


    recorder!!.startRecording()
    isRecording = true

    deeptoneStream = deeptoneSDK?.stream(
        onData = { data -> println(data)},
        onSuccess = { data ->
            println("data: $data")
        },
        onError = { e -> println(e) }
    )

    recordingThread = Thread(Runnable {
        while (isRecording) {
            val buffer = ShortArray(bufferSizeInBytes / 2)

            recorder!!.read(buffer, 0, buffer.size)

            val audioBuffer = FloatArray(buffer.size)
            for (i in buffer.indices) {
                audioBuffer[i] = buffer[i] / 32767.0f
            }

            deeptoneStream?.write(audioBuffer)
        }
    }, "AudioRecorder Thread")
    }

    recordingThread!!.start()
}

fun stopRecording() {
        if (null != recorder) {
            isRecording = false
            recorder!!.stop()
            recorder!!.release()
            recorder = null
            recordingThread = null
            deeptoneStream?.close()
        }
    }

API Reference

Please refer to the Android SDK API Reference for further details on types.