Latest Legacy

The AudioStream element Beta

The audio stream element lets you receive raw audio from active calls over a WebSocket connection in near real time.

Attributes

bidirectionalboolean

Specifies whether the audio being streamed over the WebSocket is bidirectional (the service can both read and write audio over the WebSocket) or one-way (read-only).

If the bidirectional attribute is set to true, then Plivo accepts the below parameters to accept the audio stream from your application over the WebSockets.

 

Allowed values:

event: Takes playAudio as the value
media: Takes a JSON input of the key values below
contentType: raw, wav
sampleRate: 8000 and 16000
payload: Base64-encoded raw audio
audioTrackstring

The audio track (inbound or outbound) of the underlying call that Plivo will fork and stream to the WebSocket service.
Allowed values:
inbound (only audio received by Plivo from call participants is streamed over WebSocket), outbound (only audio transmitted by Plivo to call participants is streamed over WebSocket), both(both inbound and outbound audio is streamed over the WebSocket). Default is inbound.

Note: When the bidirectional value is set to true, the audioTrack value should not be set to outbound or both.
streamTimeoutinteger

The maximum duration, in seconds, for which audio will be streamed once streaming starts. At the end of the specified duration, streaming will stop. This will have no impact on the rest of the call flow.
Needs to be a positive integer if provided. Defaults to 86,400 (24 hours).

statusCallbackUrlstring

URL notified by Plivo when one of the following events occurs:

  • Audio stream is connected and audio begins streaming (first packet is sent)
  • Audio stream is stopped intentionally or when audio stream timeout is reached
  • Audio stream failed to connect or got disconnected for any reason during an ongoing call

statusCallbackMethodstring

The HTTP verb used to invoke the status_callback_url.
Allowed values:
GET, POST Defaults to POST.

contentTypestring

Preferred audio codec and sampling rate.
Allowed values: audio/x-l16;rate=8000, audio/x-l16;rate=16000, audio/x-mulaw;rate=8000 Defaults to audio/x-l16;rate=8000.

extraHeadersstring

Key-value pairs passed to the WebSocket service along with the audio stream. These extra headers will be passed with every HTTP request made by the call.
Takes string of key-value pairs as input. Example: “test1=12,test2=123”. Total length of the string being passed should be no more than 512 bytes. Only [A-Z], [a-z], and [0-9] characters are allowed in both key and value.

Parameters sent to the statusCallbackUrl

This information is sent to statusCallbackUrl when an event is triggered.

Eventstring

Allowed values:

  • StartStream: sent when audio begins streaming post connection establishment
  • StopStream: sent when the audio stream is stopped intentionally or stream timeout has been reached
  • DroppedStream: sent when the audio stream failed to connect or got disconnected due to any reason during an ongoing call
  • Played: sent when the last packet for an inbound stream is successfully played out on the call and there is nothing else to be played on the call. Can be sent multiple times.
Note: No callback is sent when a call (rather than a stream) gets disconnected.

Errorstring

May be Could not establish connection with the remote service or Connection disconnected with the remote service.
Populated only if value of StreamAction is dropped; empty otherwise.

CallUUIDstring

Unique identifier for this call.

Fromstring

Caller number or SIP endpoint of the CallUUID sent for audio streaming.

Tostring

Destination number or SIP endpoint of the CallUUID sent for audio streaming.

ServiceURLstring

WebSocket URL to which the audio stream is connected.

ExtraHeadersstring

Key-value pairs passed as part of the audio Stream XML element.

StreamIDstring

Unique identifier for each audio stream.

Timestamptimestamp

The timestamp of when the event was generated.

Response

<Response>
	<Stream>wss://yourstream.websocket.io/audiostream</Stream>
</Response>

Example Request

1
2
3
4
5
6
from plivo import plivoxml

response = plivoxml.ResponseElement().add(plivoxml.StreamElement('
wss://yourstream.websocket.io/audiostream'))                                         

print(response.to_string())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
require 'rubygems'
require 'plivo'

include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new
    response.addStream('
wss://yourstream.websocket.io/audiostream')

  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end
1
2
3
4
5
6
7
var plivo = require('plivo');

const streamResponse = new Response();
var service_url = "wss://yourstream.websocket.io/audiostream";
streamResponse.addStream(service_url);

console.log(response.toXML());
1
2
3
4
5
6
7
8
9
10
11
12
13
<?php
    require './vendor/autoload.php';
    use Plivo\XML\Response;

    $response = new Response();

    $response->addStream("
wss://yourstream.websocket.io/audiostream");
    $ssml = $response->toXML(true);

    Header('Content-type: text/xml');
    echo($response->toXML());
?>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Example for Audio Stream XML creation
package com.plivo.examples;

import com.plivo.api.exceptions.PlivoValidationException;
import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Stream;

public class StreamXML {

  public static void main(String[] args) throws PlivoValidationException, PlivoXmlException {
    Response response = new Response().children(new Stream("
wss://yourstream.websocket.io/audiostream
"));
    System.out.println(response.toXmlString());
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
using System;
using System.Collections.Generic;

namespace PlivoExamples
{
    public class MainClass
    {
        public static void Main(string[] args)
        {
            
            Dictionary<string, string> parameter  =
                new Dictionary<string, string>();
            parameter.Add("bidirectional", "False");
            parameter.Add("audioTrack", "both");
            parameter.Add("streamTimeout", "120");
            parameter.Add("statusCallbackUrl", "https://<yourdomain>.com/confevents/");
            parameter.Add("statusCallbackMethod", "POST");
            parameter.Add("contentType", "audio/x-l16;rate=16000");
            
            Plivo.XML.Stream resp1 = new Plivo.XML.Stream("
wss://yourstream.websocket.io/audiostream",parameter);

            var output = resp1.ToString();
            Console.WriteLine(output);
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
package main

import (
	"github.com/plivo/plivo-go/v7/xml"
	"html"
)

func main() {
	response := xml.ResponseElement{
		Contents: []interface{}{
			new(xml.StreamElement).SetContents("wss://www.example.com/socketserver"),
		},
	}
	print(html.UnescapeString(response.String()))
}