JSON-RPC API
Media Generator provides an open JSON-RPC API. This allows it to be controlled from a plethora of languages including Python, C, C#, Tcl, LUA, Javascript and Java.
JSON is a text-based, human-readable format for representing simple data structures and associative arrays, also called objects. Below is a simple example of an encoding. The specification can be found here.
{
"name": "ACME Inc.",
"address": {
"street": "29 Acacia Avenue",
"city": "Oakland",
"state": "Anystate"},
"phone": [
"755 345-2233",
"776 334-8766
}
See this article for more information about JSON.
JSON-RPC is a remote procedure call protocol, similar in concept to XML-RPC or SOAP, however it is simpler defining only a handful of data types and commands. Additionally it allows for bidirectional communication between the service and the client, treating each more like peers and allowing peers to call one another or send notifications to one another. It also allows multiple calls to be sent to a peer which may be answered out of order.
{
"jsonrpc": "2.0",
"method": "subtract",
"params": {
"subtrahend": 23,
"minuend": 42},
"id": 3
}
{
"jsonrpc": "2.0",
"result": 19,
"id": 3
}
- jsonrpc - identifies the JSON as JSON RPC
- method - the name of the JSON RPC method to call
- params - the parameters to pass to the method
- id - message indentifier used to correlated method calls and results
- result - the result of the method call
See this article for more information about JSON-RPC.
JSON is supported by most languages including C, C++, C#, Java, Perl, Python, Tcl. For a complete list, check here.
Media Generator provides a JSON-RPC API using TCP/IP sockets, implemented as a server. By default, this runs on port 7474.
An audio RTP stream can be started as simply as sending:
{
"id":"1",
"method":"audio.startSession",
"jsonrpc":"2.0",
"params":{
"sessionId":"One",
"srcPort":60000,
"dstIp":"192.168.1.1",
"dstPort":60000}
}
If successful, Media Generator will respond with:
{
"id":"1",
"jsonrpc":"2.0",
"result":true
}
If it fails, for example if the stream is already running:
{
"description":"Stream with id \"One\" already exists",
"id":"1","jsonrpc":"2.0",
"result":false
}
This will send create a RTP session between Media Generator on port 60000 and 192.168.1.1:60000 using the default uLaw codec, default input source Comfort Noise. Any incoming audio from 192.168.1.1 will be played through the speaker by default.
Media Generator can support many streams in parallel, each stream is uniquely identified by the sessionId parameter ("One" in the above example). There are a variety of input sources and output sinks including the DTMF tone generator, DTMF detector, WAV reader and writer, microphone, speaker, text to speech synthesizer. These are detailed in the input and outputs section below.
To stop the stream:
{"id":"1","method":"audio.stop","jsonrpc":"2.0","params":{ "streamId":"One"}}
The order of parameters is not important, however, Media Generator sorts them alphabetically.
Each of the available methods are described below.
JSON-RPC API methods
Audio
audio.startSession
sessionId
string: uniquely identifies the session
codec
string: codec uLaw or aLaw or Speex or LPC or GSM
subcodec
string: subcodec UltraWideBand or WideBand or NarrowBand or NA
payloadType
integer: RTP payload id (optional)
srcIp
string: IP (bind) address of source
srcPort
integer: base port of session on Media Generator
dstIp
string: IP address of destination
dstPort
string: port of destination
input
string: input Microphone or File or Tone or Text or Dtmf or Silence or ComfortNoise
inputParams
file
string: file to read from
digits
string: dtmf digits to play
digitLength
integer: dtmf digit length in milliseconds
interDigitLength
integer: dmtf inter-digit time in milliseconds
aFreq
real: frequency of first tone in hertz
bFreq
real: frequency of second tone in hertz
aAmp
real: amplitude of first tone; 0.0 - 1.0
bAmp
real: amplitude of second tone; 0.0 - 1.0
text
string: text to synthesize
loop
boolean: loop input continuously
output
string: output Speaker or File or None
outputParams
file
string: file to write to
securityParams
securityService
string: null or security or authentication or both
authentication
string: null or usttmmhv2 or ustaes128xmac or hmacsha1 or stronghold
cipher
string: null or aes128icm or seal or aes128cbc or stronghold
txKey
string: transmission key
rxKey
string: reception key
tester
string: test unit PathValidator or QualityAnalyzer
testerParams
sendId
integer: 0..65535 DTMF stream identifier to generate
receiveId
integer: 0..65535 DTMF stream identifier to detect
payloadSource
string: .pcap file name (in audio directory)
payloadSampleRate
integer: sample rate in khz e.g. 8000
localListen
boolean: create an additional connection to self (localhost)
acceptOwnPackets
boolean: instruct RTP stack to accept packets it originated
detectDtmf
boolean: enable the DTMF detector
audio.startTester
sessionId
string: uniquely identifies the session
srcIp
string: IP (bind) address of source
srcPort
integer: base port of session on Media Generator
dstIp
string: IP address of destination
dstPort
string: port of destination
securityParams
securityService
string: null or security or authentication or both
authentication
string: null or usttmmhv2 or ustaes128xmac or hmacsha1 or stronghold
cipher
string: null or aes128icm or seal or aes128cbc or stronghold
txKey
string: transmission key
rxKey
string: reception key
codec
string: alaw or ulaw or user
payloadType
integer: RTP payload id (optional)
tester
string: pathValidator or qualityAnalyzer
testerParams
pathValidator:
sendId (optional)
string: integer 0..65535 DTMF stream identifier to generate
receiveId (present only if sendId is set)
string: integer 0..65535 DTMF stream identifier to detect
qualityAnalyzer:
payloadSource (optional)
string: pcap file name
payloadSampleRate (optional)
string: sample rate in khz e.g. 8000
audio.stopTester
sessionId
string: identifies the session to stop
audio.stopSession
sessionId
string: identifies the session to stop
audio.stopAll
None
audio.addDestination
sessionId
string: identifies the session to add to
dstIp
string: IP address of destination
dstPort
string: port of destination
audio.deleteDestination
sessionId
string: identifies the session to remove the destination from
dstIp
string: IP address of destination
dstPort
string: port of destination
audio.changeInput
sessionId
string: identifies the session to change
input
string: input Microphone or File or Tone or Text or Dtmf or Silence or ComfortNoise
inputParams
object: input specific list of parameters
audio.setImpairments
sessionId
string: identifies the session to affect
impairmentParams
jitter
integer: standard deviation in milliseconds
loss
integer: percentage 0-100%
burstiness
integer: percentage 0-100%
Video
video.startTester
sessionId
string: uniquely identifies the session
srcIp
string: IP (bind) address of source
srcPort
integer: base port of session on Media Generator
dstIp
string: IP address of destination
dstPort
string: port of destination
securityParams
securityService
string: null or security or authentication or both
authentication
string: null or usttmmhv2 or ustaes128xmac or hmacsha1 or stronghold
cipher
string: null or aes128icm or seal or aes128cbc or stronghold
txKey
string: transmission key
rxKey
string: reception key
codec
string: user
payloadType
integer: RTP payload id (optional)
tester
string: qualityAnalyzer
testerParams
qualityAnalyzer:
payloadSource (optional)
string: pcap file name
payloadSampleRate (optional)
string: sample rate in khz e.g. 90000
video.stopTester
sessionId
string: identifies the session to stop
JSON-RPC API events
Audio
audio.qualityAnalyserEvent
sessionId
string: uniquely identifies the session
burstDensity
string: percent
burstLength
string: milliseconds
delay
string: milliseconds
discardRate
string: percent
gapDensity
string: percent
gapLength
string: milliseconds
jitter
string: milliseconds
lossRate
string: percent
mosPq
string: 1-5
audio.pathValidationTesterEvent
sessionId
string: uniquely identifies the session
result
string: passed|failed
reason
string: description of failure
audio.textEvent
sessionId
string: uniquely identifies the session
type
string: loop|finished
audio.fileEvent
sessionId
string: uniquely identifies the session
type
string: loop|finished
audio.telephonyEvent
sessionId
string: uniquely identifies the session
digit
string: detected DTMF digit
Video
video.qualityAnalyserEvent
sessionId
string: uniquely identifies the session
burstDensity
string: percent
burstLength
string: milliseconds
delay
string: milliseconds
discardRate
string: percent
gapDensity
string: percent
gapLength
string: milliseconds
jitter
string: milliseconds
lossRate
string: percent
mosPq
string: 1-5
Description of Inputs and Outputs
comfortNoise
- Input only
- Low intensity statistical noise
- Parameters
None.
silence
- Input only
- Parameters
None.
microphone
- Input only
- Uses the system microphone as the audio input
- Parameters
None.
speaker
- Output only
- Parameters
None
file
- Input/Output
- 16bit PCM WAV support
- Parameters
filename
string: filename of wav to read or write
loop
boolean: continuously loop
- Events
fileEvent
- Parameters
event
string: event description (e.g. Stopped)
tone
- Output only
- Generic dual tone generation
- Parameters
aFreq
real: frequency of first tone in hertz
bFreq
real: frequency of second tone in hertz
aAmp
real: amplitude of first tone; 0.0 - 1.0
bAmp
real: amplitude of second tone; 0.0 - 1.0
text
- Output only
- Text To Speech (TTS) synthesizer. Plays text as speech.
- Parameters
text
string: text to synthesize
loop
boolean: continuously loop
- Events
textEvent
- Parameters
event
string: event description (e.g. Stopped)
dtmf
- Output only
- Plays DTMF digits and strings
- Parameters
digits
string: digits to play
digitLength
integer: digit length in milliseconds
interDigitLength
integer: inter-digit time in milliseconds
- Events
telephonyEvent
- Parameters
digit
string: DTMF digit received
none
- Output only
- Null device
- Parameters
None.
Controlling with Python
Using Python is very straightforward and ideal for controlling Media Generator. A basic framework follows.
import sys
import simplejson as json
from socket import *
id= 0 # Transaction id
def send(s,r): # Simple function to encode JSON, send, receive result,
# decode and check transaction id and result
rjsonrpc= "2.0" # Fill in standard parts
rid= id
s.send( json.dumps(r)+"\n") # Send to the Media Generator
j= s.recv(1024) # Get result
o= json.loads(j) # Convert from JSON to Python object
if oid == id: # Check the transaction id matches what we sent
if oresult == False:
print("Error! Returned false" + odescription)
else:
print("Error! Transaction id wrong")
id= id + 1 # increment transaction id
return
def receive(s,r): # Simple function to encode JSON, send, receive result,
# decode and check transaction id and result
j= s.recv(1024) # Get event
r= json.loads(j) # Convert from JSON to Python object
return
mgHost = "192.168.1.66" # IP address of Media Generator
mgPort = 7474 # Port of Media Generator
s = socket(AF_INET, SOCK_STREAM) # create a TCP socket
s.connect((mgHost, mgPort)) # connect to server on the port
# Send commands
s.close()
This function accepts a Python list and converts to to JSON, sends it as JSON-RPC, waits, decodes and checks the result
The command to starting a stream containing silence looks like this:
send( s, { "method":"audio.startSession",
"params":{ "sessionId":"One",
"dstIp":"192.168.1.254",
"srcPort":60000,
"dstPort":60000}})
