Latest Legacy

Initiate an audio Stream

This method lets you initiate an audio stream for an active call and send that stream to a secure WebSocket URL.

API Endpoint

POSThttps://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/

Attributes

Service_urlstringrequired

WebSocket URL to which the audio stream is to be initiated.

Example: wss://mystream.ngrok.io/audiostream

If a qualified URL is not present, or an active stream is already supplied to the URL, a 400 error is returned.

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-l16, audio/x-mulaw
sampleRate: 8000 and 16000
payload: Base64-encoded raw audio
audio_trackstring

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 audio_track value should not be set to outbound or both.
stream_timeoutinteger

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).

status_callback_urlstring

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

status_callback_methodstring

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

content_typestring

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

extra_headersstring

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.

Response

{
 "message": "audio streaming started",
 "api_id":  "c7b69074-58be-11e1-86da-adf28403fe48",					
 "stream_id": "b7b69074-58be-11e1-86da-adf28403fe48" 
}

Example Request

1
2
3
4
5
6
7
import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')

response= client.calls.start_stream(call_uuid='506f0d9f-5961-4c3f-b595-732b36c24e29',service_url='wss://8309-49-36-97-128.mywebsocket.io',bidirectional=False, audio_track='both',stream_timeout=86400,status_callback_url='https://<yourdomain>.com/events/',status_callback_method='POST',content_type='audio/x-l16;rate=16000',extra_headers="Test1=Test2,Test3=Test4")

print(response)
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
require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

api = RestClient.new("<auth_id>","<auth_token>")

begin
  response = api.calls.start_stream( "227ff3c3-1562-4316-819f-217f638890f6","wss://www.example.com/socketserver",
      {
        
        bidirectional: false,
        audio_track: "both",
        stream_timeout: 86400,
        status_callback_url: "https://<yourdomain>.com/events/",
        status_callback_method: "POST",
        content_type: "audio/x-l16;rate=16000",
        extra_headers: "Test1=Test2,Test3=Test4"
        }
    )
  puts response
rescue PlivoRESTError => e
  puts 'Exception: ' + e.message
end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Create an audio stream on a call

'use strict';

var plivo = require('plivo');

(function main() {
    var client = new plivo.Client(<auth_id>, <auth_token>);
    client.calls.stream(<call_uuid>, "wss://www.example.com/socketserver",
        {
            bidirectional: false,
            audioTrack: "both",
            streamTimeout: 86400,
            statusCallbackMethod: "POST",
            contentType: "audio/x-l16;rate=16000"
        }
    ).then(function (response) {
        console.log(response);
    }, function (err) {
        console.error(err);
    });
})();
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
28
29
<?php
/**
 * Create an audio stream on a call
 */
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>","<auth_token>");
try {
    
    $response = $client->calls->startStream(
        "d08b6798-c8eb-4dad-b8c5-4e8d2bdb718a",
        array('service_url'=>"wss://www.example.com/socketserver",
        'bidirectional' => false,
        'audio_track' => "both",
        'stream_timeout' => 86400,
        'status_callback_url' => "https://<yourdomain>.com/confevents/",
        'status_callback_method' => "POST",
        'content_type' => "audio/x-l16;rate=16000",
        'extraheaders' =>"Test1=Test2,Test3=Test4"

    )
    );

    print_r($response);
}
catch (PlivoRestException $ex) {
    print_r($ex);
}
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
28
29
30
31
32
33
34
35
36
37
package com.plivo.examples.audioStream;

import java.io.IOException;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.call.Call;
import com.plivo.api.models.call.CallCreateResponse;
import com.plivo.api.models.call.actions.CallStreamCreateResponse;
import com.plivo.api.models.call.actions.CallStreamCreator;

/**
 * Create an audio stream on a call
 */
class createStreamAPI {

  public static void main(String [] args) {

    Plivo.init("MANWVLYTK4ZWU1YTY4QA", "ZDI4ZTc3ZWNmMzJhM2M2OGI4MGVjZmJmNmFjNDRl");

    Map map=new HashMap();
    map.put(1,"Amit");


    try {
      CallStreamCreateResponse response = Call.streamer("874a6bfa-da76-4279-b8c5-2d12743c045b","wss://ea22-120-138-116-194.ngrok.io")
        .streamTimeout(23).bidirectional(false).audioTrack("both").statusCallbackUrl("http://plivobin.non-prod.plivops.com/1pdc8e11").statusCallbackMethod("POST").contentType("audio/x-l16;rate=16000").extraHeaders("Test1=Test2,Test3=Test4").stream();
      System.out.println(response);

    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}
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
28
29
30
31
/**
 * Create an audio stream on a call
 */
using System;
using System.Collections.Generic;
using Plivo;
using Plivo.Exception;

namespace PlivoExamples
{
    internal class Program
    {
        public static void Main(string[] args)
        {
            var api = new PlivoApi("<auth_id>","<auth_token>");
            try
            {
                var response = api.Call.StartStream(callUuid: "d08b6798-c8eb-4dad-b8c5-4e8d2bdb718a", serviceUrl: "wss://www.example.com/socketserver",
                                    bidirectional: "False", audioTrack: "both",
                                    streamTimeout: "86400",statusCallbackMethod: "POST", statusCallbackUrl: "https://<yourdomain>.com/confevents/", contentType: "audio/x-l16;rate=16000",
                                    extraHeaders: "Test1=Test2,Test3=Test4");
                );
                Console.WriteLine(response);
            }
            catch (PlivoRestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}
1
2
3
4
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"service_url": "wss://mystream.ngrok.io/audiostream","bidirectional": true,"status_callback_url": "https://webhook.site/22ffd771-4337-4f5e-b9e0-00c24bd2c119"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/
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
28
29
30
31
32
33
34
35
package Audio_Streaming

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

// Create an audio stream on a call
//package main

func main() {
client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
if err != nil {
fmt.Print("Error", err.Error())
return
}
//Method for create Stream
response , err := client.Calls.Stream("14885f81-ecb5-477d-a361-930276352966", plivo.CallStreamParams{

ServiceUrl: "wss://a33b-120-138-116-194.ngrok.io",
Bidirectional: false,
AudioTrack: "both",
StreamTimeout: 300,
StatusCallbackMethod: "POST",
StatusCallbackUrl: "http://plivobin.non-prod.plivops.com/1pdc8e11",
ContentType: "audio/x-l16;rate=16000",
ExtraHeaders : "Test1=Test2,Test3=Test4"
},
)
if err != nil {
fmt.Print("Error", err.Error())
return
}
fmt.Printf("Response: %#v\n", response)
}