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: audio/x-l16, audio/x-mulaw 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.
keepCallAliveBoolean	This parameter signifies whether the stream element should be executed alone, without proceeding to execute the subsequent elements in the XML instruction. It applies only when the bi-directional audio stream is set to true. Any elements following the stream in the XML instruction will execute only after the stream is disconnected. Allowed values: true, false Default: false

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 ClearedAudio: Transmitted when buffered audio files are cleared following the clearAudio command from your application. PlayedStream: The "PlayedStream" event serves as an acknowledgment of the checkpoint event from the customer. It is emitted when all preceding media events before the checkpoint event have been successfully played back to the end user. 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 bidirectional = "true" keepCallAlive="true" >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()))
}

Rate this page

🥳 Thank you! It means a lot to us!