ToneTip SDK

ToneTip SDK is a JavaScript library that allows you to decode ToneTips from audio sources. Whether you're working on a music app, podcast platform, or any other audio-related project, this SDK helps you integrate ToneTip detection seamlessly.

Installation

To install the SDK, use npm:

npm install tone-tip-sdk

API Key Requirement

To use the SDK, you must generate an API key from the ToneTip Dashboard. The API key is required and the SDK will not function without it. Note that access to the API is a paid service.

Basic Usage

Below is a basic example of how to use ToneTip SDK in a React application:

import React, { useCallback, useEffect, useState } from "react";
import { AudioListener } from "tone-tip-sdk";
import "./ListeningComponent.css";

const API_KEY = process.env.REACT_APP_TONE_TIP_API_KEY;

const BasicComponent = () => {
  const [listener, setListener] = useState<AudioListener | null>(null);
  const [error, setError] = useState("");
  const [loading, setLoading] = useState(true);
  const [isListening, setIsListening] = useState(false);

  const onError = (err: unknown) => {
    console.error("Error Tonetip: ", err);
  };

  const onDetected = (toneTipTag: string) => {
    console.log("TonetipTag decoded:", toneTipTag);
  };

  const createListener = useCallback(async () => {
    if (!API_KEY) return;

    try {
      const listenerT = new AudioListener(API_KEY, {
        onDetected,
        onError,
        onListeningChange: (state: boolean) => {
          setIsListening(state);
        },
        isSandbox: true,
      });

      setListener(listenerT);
      setLoading(false);
    } catch (error: unknown) {
      let errorMessage = "An unknown error occurred.";
      if (error instanceof Error) {
        errorMessage = error.message;
      }
      setError(errorMessage);
    }
  }, []);

  useEffect(() => {
    createListener();
  }, [createListener]);

  useEffect(() => {
    return () => {
      listener?.stopListening();
    };
  }, [listener]);

  if (loading) {
    return <p className="loading">Loading...</p>;
  }

  if (error) {
    return <div className="error-container">{error}</div>;
  }

  return (
    <div className="listening-component-main-container">
      <button
        className={`listener-btn ${isListening ? "listening" : ""}`}
        onClick={() =>
          !isListening ? listener?.listening() : listener?.stopListening()
        }
      >
        {isListening ? "Stop listening" : "Start listening"}
      </button>
    </div>
  );
};

export default BasicComponent;

Framework Compatibility

Although the example above is in React, the SDK can be used in other JavaScript frameworks and libraries, including:

• Vue.js
• Angular
• Vite
• Node.js (for server-side processing if needed)

Configuration Options

The AudioListener constructor accepts an optional configuration object:

type AudioListenerOptions = {
  logs?: LogLevel; // Enables debug logs at different levels
  isSandbox?: boolean; // Uses sandbox or production mode
  onAudioListening?: (audioLevel: number) => void; // Returns real-time audio level
  onDetected?: (toneTipTag: string) => void; // Callback when a ToneTip is decoded
  onError?: (error: unknown) => void; // Callback for handling errors
  onListeningChange?: (state: boolean) => void; // Callback to track listening state
};

• logs: Enables debugging logs for different levels.
• isSandbox: When true, uses the sandbox mode instead of production.
• onAudioListening: Returns real-time audio levels, useful for creating UI effects such as sound waves.
• onDetected: Returns the decoded ToneTip tag.
• onError: Triggers when an error occurs.
• onListeningChange: Provides the current listening state, useful for updating UI elements.

All options are optional, except for the API key, which is required and must be passed as the first argument to AudioListener.

Full Documentation

For complete details on all available methods and configurations, visit our full documentation: tt.media/docs.