Pass Different Audio Codecs - Telephony API

We're working to improve this content! :star:

Sometimes you need to pass different audio codecs when passing the audio. This
example shows how to pass them. The codecs currently supported are:

OPUS:

  • Supported Sample Rates -- 16000Hz, 24000Hz,48000Hz
  • Both CBR (Constant Bitrate) and VBR (Variable Bitrate) are supported
  • Support for in-band FEC

SPEEX:

  • Supported Sample Rates -- 16000Hz
  • VBR is not supported

LINEAR16

  • Supported Sample Rates -- 44100Hz

MULAW

  • Supported Sample Rates -- 8000Hz

📘

We recommend using OPUS as compared to other codecs because it provides
the most flexibility in terms of audio transportation and also has packet
retransmission mechanisms like FEC which work well, especially in low-bandwidth
scenarios.

Throughout the documentation you'll find various references to these variable names, which you will have to replace with your values:

KeyDescription
APP_IDThe application ID you get from the home page of the platform.
APP_SECRETThe application secret you get from the home page of the platform.
AUTH_TOKENThe JWT you get after authentication with Sybml.
DEFAULT_PHONE_NUMBERA phone number that you want the API to connect to. Be sure to include the country code.
EMAIL_ADDRESSThe email address you wish to send the summary email to.

View on Github

Getting started

This example runs on node server, so we will use @symblai/symbl-js package.

const {sdk} = require('@symblai/symbl-js');

Initialize the SDK

Let's start by initialising @symblai/symbl-js sdk

await sdk.init({
  appId: APP_ID,
  appSecret: APP_SECRET,
  basePath: 'https://api.symbl.ai'
});

Connect to Endpoint

Now after we initialized, we need to start the connection by running

const connection = await sdk.startEndpoint(endpointConfig);

Set Up Configuration Options

So how do you pass custom codecs? It's as simple as passing custom audio config

endpoint: {
  //*****************Custom Audio Config******************
  audioConfig: {
    encoding: 'OPUS',
    sampleRate: 16000,
  },
  //******************************************************
  type: 'pstn',
  phoneNumber: DEFAULT_PHONE_NUMBER,
},

If you have a requirement to use a codec not included in the ones above or have any other queries, please drop an e-mail to [email protected]

📘

If you have any questions or concerns about our API, you can join our Support Slack or send us an email at [email protected]

Full Code Example

/*
 * This example shows how to pass in different Audio Codecs. The ones currently supported are
 *   OPUS:
 *     * Supported Sample Rates -- 16000Hz, 24000Hz, 48000Hz
 *     * Both CBR (Constant Bitrate) and VBR (Variable Bitrate) are supported
 *     * Support for in-band FEC
 *
 *   SPEEX:
 *     * Supported Sample Rates -- 16000Hz
 *     * VBR is not supported
 *
 *   LINEAR16:
 *     * Supported Sample Rates -- 44100Hz
 *
 *   MULAW:
 *     * Supported Sample Rates -- 8000Hz
 *
 *   NOTE: We recommend using OPUS as compared to other codecs because it provides the most flexibility in terms of
 *         audio transportation and also has packet retransmission mechanisms like FEC which work well especially
 *         in low-bandwidth scenarios.
 *
 *   If you have a requirement to use a codec not included in the ones above or have any other queries,
 *   please drop an e-mail to [email protected]
 */
const {sdk, SpeakerEvent} = require('@symblai/symbl-js')

const getScheduleEvent = (sdk, connectionId) => {
  return (eventType, user, time) => {
    setTimeout(() => {
      const speakerEvent = new SpeakerEvent({
        type: eventType,
        user,
      })
      speakerEvent.timestamp = new Date().toISOString()

      console.log(
        `Pushing event [${speakerEvent.timestamp}] ${speakerEvent.type} : ${speakerEvent.user.name}`,
      )

      sdk.pushEventOnConnection(connectionId, speakerEvent.toJSON(), (err) => {
        if (err) {
          console.error('Error during push event.', err)
        } else {
          console.log('Event pushed!')
        }
      })
    }, time * 1000)
  }
}

const users = {
  john: {
    userId: '[email protected]',
    name: 'John',
  },
  mary: {
    userId: '[email protected]',
    name: 'Mary',
  },
  tim: {
    userId: '[email protected]',
    name: 'Tim',
  },
  jennifer: {
    userId: '[email protected]',
    name: 'Jennifer',
  },
}
;(async () => {
  try {
    // Initialize the SDK
    await sdk.init({
      appId: APP_ID,
      appSecret: APP_SECRET,
      basePath: 'https://api.symbl.ai',
    })

    const connection = await sdk.startEndpoint({
      endpoint: {
        //*****************Custom Audio Config******************
        audioConfig: {
          encoding: 'OPUS',
          sampleRate: 16000,
        },
        //******************************************************
        type: 'pstn',
        phoneNumber: DEFAULT_PHONE_NUMBER,
      },
      actions: [
        {
          invokeOn: 'stop',
          name: 'sendSummaryEmail',
          parameters: {
            emails: ['[email protected]'],
          },
        },
      ],
      data: {
        session: {
          name: 'Ship-wide nanomachines, to the center.',
        },
      },
    })
    const connectionId = connection.connectionId
    console.log('Successfully connected.', connectionId)

    const scheduleEvent = getScheduleEvent(sdk, connectionId)

    setTimeout(() => {
      // This is just for interactive purpose was to show the elapsed time.

      scheduleEvent(SpeakerEvent.types.startedSpeaking, users.john, 0)
      scheduleEvent(SpeakerEvent.types.stoppedSpeaking, users.john, 4)

      scheduleEvent(SpeakerEvent.types.startedSpeaking, users.mary, 4)
      scheduleEvent(SpeakerEvent.types.stoppedSpeaking, users.mary, 9)

      // Scheduling stop endpoint call after 60 seconds
      setTimeout(() => {
        console.log('stopping connection ' + connection.connectionId)
        sdk
          .stopEndpoint({
            connectionId,
          })
          .then(() => {
            console.log('Stopped the connection')
          })
          .catch((err) =>
            console.error('Error while stopping the connection.', err),
          )
      }, 10000)
    }, 1000)
  } catch (err) {
    console.error('Error in SDK initialization.', err)
  }
})()

Running The Example

Create a JavaScript file named app.js and copy this code into the file. Fill in the placeholder values with the proper values. Use npm to install the required libraries: npm install @symblai/symbl-js. Now in the terminal run

$ node app.js

If successful you should receive a response in the console.

📘

If you have any questions or concerns about our API, you can join our Support Slack or send us an email at [email protected]


Did this page help you?