Open topic with navigation

Q-SYS PA Remote API

The Q-SYS Public Address Remote API, or PARAPI, is a TCP/IP command protocol intended to allow third-party systems to programmatically issue and monitor pages using the PA features of Q-SYS. The command and response syntax is based on JSON-RPC version 2.0 (see http://json­rpc.org/wiki/specification). The PA.PageSubmit command allows the client to issue a page, either voice or message play. PA.ZoneStatusWatch allows the client to monitor the activity of the PA Router output zones.

ClosedCommands and Notifications

With the PA.PageSubmit command, a client submits a page specification and gets a PageID “handle” back from Q-SYS that can be used to subsequently Start, Stop, or Cancel the page. The PageID also appears in notifications from Q-SYS on the progress of the page in the system.

PA.ZoneStatusConfigure supports starting and stopping PA.ZoneStatus notifications from Q-SYS. These notifications give updates on the activity of each PA Router output zone.

In addition to the notifications sent by Q-SYS, Q-SYS returns a JSON-RPC result or error for each command that includes a JSON-RPC id. The result from the PA.PageSubmit command, for example, contains a PageID.

If greater than 60 seconds elapses between commands sent to the PARAPI server, the socket connection is closed. The client can send the NoOp command periodically it there isn't enough other command activity to keep the connection alive.

Commands (to Q-SYS)

  • PA.PageSubmit : Submit a page specification. Response contains a PageID.
  • PA.PageStart : Start a page.
  • PA.PageStop : End a voice page (when the announcer is finished talking).
  • PA.PageCancel : Cancel a page.
  • PA.ZoneStatusConfigure : Configure zone status change notifications.

Notifications (from Q-SYS)

  • PA.PageStatus : Page status update.
  • PA.ZoneStatus : Zone status change.
ClosedJSON-RPC Error Codes

The following PARAPI error codes can be returned as the code value in a JSON­RPC error object.

Example: {"id":"2235","jsonrpc":"2.0","error":{"message":"Message file does not exist","code":4}}

Code

Description

1

Bad Parameters – one or more of the parameters is bogus.

2

Bad PageID – the PageID refers to a Page Request which does not exist.

3

Bad Request – could not create requested Page Request.

4

Bad File – Message file doesn't exist.
ClosedParameters

PA.ZoneStatusConfigure

Parameter

Type

Value

Notes

Enabled

boolean

  

Enables/disables zone status updates.

PA.PageSubmit

Parameter

Type

Value

Notes

Overrides Global Setting

Parameter Required

Parameter Applies to Mode

Mode

string

"message" or "live" or "delay" or "auto"

Specifies the type of page. “live”, “delay”, and “auto” are all voice pages.

-

Y

live

delay/auto

message

Description

string

 

Appended to the completion event generated for the page (events appear in the Q-SYS Core Manager Event Log).

-

N

Y

Y

Y

Zones

integer array

 

Array of zone indices.

-

Y (and/or ZoneTags)

Y

Y

Y

ZoneTags

string array

 

Array of zone tag strings.

-

Y (and/or Zones)

Y

Y

Y

Priority

integer

1-­n

1 is highest priority.

-

Y

Y

Y

Y

Preamble

url string

audio file path

The preamble to play preceding the voice page or message.

-

N

Y

Y

Y

Message

url string

audio file path

The message to play, located in the Messages directory.

-

Y, if Mode == message

N

N

Y

MessageDelete

boolean

 

The message file will be deleted on page completion.

-

N

N

N

Y

Station

integer

1-­n

n is the number of PA Router Page Station inputs.

-

Y, if Mode != message

Y

Y

N

Start

boolean

 

Start the Page after Submitting it (otherwise, the client must issue a PA.PageStart).

-

N

Y

Y

Y

QueueTimeout

integer

seconds

Time before delayed page times out, 0 means infinite, ­1 means no queuing (i.e. page will fail if zones are not ready).

Y

N

N

Y

Y

Archive

boolean

 

Archive the page on completion.

Y

N

Y

Y

Y

Split

boolean

 

Allow partial page.

Y

N

Y

Y

Y

RetryCount

integer

0­-n

Number of retries when page is interrupted on one or more zones.

Y

N

N

Y

Y

MaxPageTime

integer

seconds

Time before a voice page times out.

Y

N

Y

Y

N

CancelDelay

integer

seconds

Time during which delayed pages and messages are held for possible cancellation.

Y

N

N

Y

Y

Originator

string

 

Optional string used for logging. Default value is "QRAPI".

-

-

-

-

-

PA.PageStatus

State

SubState

Count

Message

 

 

 

Mode=live

Mode=delay

Mode=message

ready

queued

­

Busy1

­

Message not ready2

 

immediate

­

Ready to Page

Ready to Record

Ready to play message

wait

preamble

­

Playing Preamble

­

­

 

zones

­

Please wait

Waiting to playback

Waiting to playback

 

system

­

­

Waiting to playback

 

 

cancel

Y

­

Waiting to playback3

Waiting to playback3

input

live

Y

Paging3

­

­

 

record

Y

­

Recording3

­

output

output

­

­

Playing message4

Playing message4

done

success

­

Page complete

Playback complete

Playback complete

 

cancel

­

Page canceled

Playback canceled

Playback canceled

 

timeout

­

Page timeout

Queue timeout, playback canceled

Queue timeout, playback canceled

 

interrupt

­

Page interrupted

Playback interrupted

Playback interrupted

 

fail

­

?

?

Message failed2
1. Zones are busy.
2. Issued if system hasn't moved file into buffer yet, or if message file doesn't exist. But, state will move from “Message not ready” to “Ready to play message” if file comes into existence. If a Start is issued while file doesn't exist, status will move to done.fail: “Message failed”.
3. input.cancel, input.live and input.record are issued once per second, with a Count parameter that counts down from CancelDelay or MaxPageTime to zero.
4. Includes optional Preamble playback.

Note: After a Page is submitted with PA.PageSubmit, it moves to the ready.queued or ready.immediate state. When PA.PageStart is issued on that Page, it will move to the wait.x or input.x state. Mode = delay or message type Pages will then move to the output.output state. Finally, the Page will move to the done.x state.

ClosedUploading, Deleting, and Referencing Audio Files

The Q-SYS Core has CGI scripts that support uploading and deleting files. Files can be uploaded to the Audio, Messages, and Preambles directories, or sub-directories within those.

Files referenced in the PA Remote API must either be in the Messages or Preambles directory - Message files must be in the Messages directory, and Preamble files must be in the Preambles directory. The parameters in the API that reference those files should not include the Messages or Preambles part of the path.

To upload, call HTTP PUT on the URL http://core_ip_address/cgi-bin/media_put?file=path/file_name

To delete, call HTTP GET on the URL http://core_ip_address/cgi-bin/media_delete?file=path/file_name

Example (using curl)

==> curl.exe -T bassdrum.wav http://172.22.100.133/cgi-bin/media_put?file="Messages/t1.wav"

<== <HTML><HEAD><B>Success</B></HEAD><BODY><BR />File put<fault code="0" pretty="No fault" extra="File put" /></BODY></HTML>

==> curl.exe http://172.22.100.133/cgi-bin/media_delete?file="Messages/t1.wav"

<== <HTML><HEAD><B>Success</B></HEAD><BODY><fault code="0" pretty="No fault" extra=""
/></BODY></HTML>
ClosedExamples

Live Page

The client submits a live page request, receives a PageID as a result, and then issues a start on that page. When the input is ready, notifications with State=”input” and SubState=”live” are received once per second with a Count indicating how many seconds are left before MaxPageTime expires. When the client is finished, it issues a Stop and gets a final notification that the page was successful.

==> {"id":"8561","method":"PA.PageSubmit","jsonrpc":"2.0","params":{"Zones":[2],"Preamble":"Chime long ascending triple.wav","Description":"Remote Client XYZ","ZoneTags":["Terminal B Retail"], "MaxPageTime":45,"Mode":"live","Station":4,"Priority":3}}

<== {"id":"8561","jsonrpc":"2.0","result":{"PageID":895}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"State":"ready","Message":"Ready to page","SubState":"immediate","PageID":895}}

==> {"id":"4549","method":"PA.PageStart","jsonrpc":"2.0","params":{"PageID":895}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"State":"wait","Message":"Please wait","SubState":"zones","PageID":895}}

<== {"id":"4549","jsonrpc":"2.0","result":"OK"}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"State":"wait","Message":"Playing preamble","SubState":"preamble","PageID":895}}

<==
{"method":"PA.PageStatus","jsonrpc":"2.0","params":{"State":"input","Message":"Paging","SubState":"live"," PageID":895}}

<==
{"method":"PA.PageStatus","jsonrpc":"2.0","params":{"Message":"Paging","Count":45,"SubState":"live","Stat e":"input","PageID":895}}

<==
{"method":"PA.PageStatus","jsonrpc":"2.0","params":{"Message":"Paging","Count":44,"SubState":"live","Stat e":"input","PageID":895}}

<==
{"method":"PA.PageStatus","jsonrpc":"2.0","params":{"Message":"Paging","Count":43,"SubState":"live","Stat e":"input","PageID":895}}

<==
{"method":"PA.PageStatus","jsonrpc":"2.0","params":{"Message":"Paging","Count":42,"SubState":"live","Stat e":"input","PageID":895}}

==> {"id":"8047","method":"PA.PageStop","jsonrpc":"2.0","params":{"PageID":895}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"State":"done","Message":"Page complete","SubState":"success","PageID":895}}

<== {"id":"8047","jsonrpc":"2.0","result":"OK"}

Message Play

The client submits a message play request with Start set to true, receives a PageID as a result, and then receives notifications indicating the message is queued and then waiting for... Then, notifications with State=”input” and SubState=”cancel” are received once per second with a Count indicating how many seconds are left before CancelDelay expires. When the Preamble starts playing, a output.output notification is received, and when the Message is finished playing, a done.success notification is received.

==> {"id":"8561","method":"PA.PageSubmit","jsonrpc":"2.0","params":{"Zones":[2],"Description":"Remote Client XYZ","QueueTimeout":30,"ZoneTags":["Terminal B Retail"],"Message":"ann2.wav","Preamble":"Chime long ascending triple.wav","Start":true,"Mode":"message","CancelDelay":5,"Priority":3}}

<== {"id":"8561","jsonrpc":"2.0","result":{"PageID":7}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"State":"ready","Message":"Message not ready","SubState":"queued","PageID":7}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"State":"wait","Message":"Waiting to playback","SubState":"cancel","PageID":7}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"Message":"Waiting to playback", "Count":5,"SubState":"cancel","State":"wait","PageID":7}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"Message":"Waiting to playback", "Count":4,"SubState":"cancel","State":"wait","PageID":7}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"Message":"Waiting to playback", "Count":3,"SubState":"cancel","State":"wait","PageID":7}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"Message":"Waiting to playback", "Count":2,"SubState":"cancel","State":"wait","PageID":7}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"Message":"Waiting to playback", "Count":1,"SubState":"cancel","State":"wait","PageID":7}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"State":"wait","Message":"Waiting to playback","SubState":"system","PageID":7}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"State":"output","Message":"Playing message","SubState":"output","PageID":7}}

<== {"method":"PA.PageStatus","jsonrpc":"2.0","params":{"State":"done","Message":"Playback complete","SubState":"success","PageID":7}}

Zone Status Watch

The client sends a PA.ZoneStatusWatch command with a JSON-RPC id and gets a response. Immediately, the status of each zone output of the PA Router is sent as a series of notifications (in this case, 8 zones). Subsequently, as pages are made, more status update notifications are sent. A PA.ZoneStatusWatch is then sent to stop the notifications.

==> {"id":"8185","jsonrpc":"2.0","method":"PA.ZoneStatusWatch"}
<== {"id":"8185","jsonrpc":"2.0","result":"OK"}

<== {"method":"PA.ZoneStatus","jsonrpc":"2.0","params":{"Time":"2012-05-14T16:57:21Z", "Zone":1,"Active":false}}
<== {"method":"PA.ZoneStatus","jsonrpc":"2.0","params":{"Time":"2012-05-14T16:57:21Z", "Zone":2,"Active":false}}
<== {"method":"PA.ZoneStatus","jsonrpc":"2.0","params":{"Time":"2012-05-14T16:57:21Z", "Zone":3,"Active":false}}
<== {"method":"PA.ZoneStatus","jsonrpc":"2.0","params":{"Time":"2012-05-14T16:57:21Z", "Zone":4,"Active":false}}
<== {"method":"PA.ZoneStatus","jsonrpc":"2.0","params":{"Time":"2012-05-14T16:57:21Z", "Zone":5,"Active":false}}
<== {"method":"PA.ZoneStatus","jsonrpc":"2.0","params":{"Time":"2012-05-14T16:57:21Z", "Zone":6,"Active":false}}
<== {"method":"PA.ZoneStatus","jsonrpc":"2.0","params":{"Time":"2012-05-14T16:57:21Z", "Zone":7,"Active":false}}
<== {"method":"PA.ZoneStatus","jsonrpc":"2.0","params":{"Time":"2012-05-14T16:57:21Z", "Zone":8,"Active":false}}

<== {"method":"PA.ZoneStatus","jsonrpc":"2.0","params":{"PriorityName":"Emergency Messages","Time":"2012-05-14T16:57:24Z","Zone":1,"Priority":2,"Station":1,"Active":true}}
<== {"method":"PA.ZoneStatus","jsonrpc":"2.0","params":{"PriorityName":"Emergency Messages","Time":"2012-05-14T16:57:24Z","Zone":5,"Priority":2,"Station":1,"Active":true}}

<== {"method":"PA.ZoneStatus","jsonrpc":"2.0","params":{"Time":"2012-05-14T16:57:26Z", "Zone":1,"Active":false}}
<== {"method":"PA.ZoneStatus","jsonrpc":"2.0","params":{"Time":"2012-05-14T16:57:26Z", "Zone":5,"Active":false}}

==> {"id":"9204","jsonrpc":"2.0","method":"PA.ZoneStatusWatchStop"}
<== {"id":"9204","jsonrpc":"2.0","result":"OK"}

Software and Firmware | Resources | QSC Self Help Portal | Q-SYS Help Feedback

Copyright © 2019 QSC, LLC. Click here for trademark and other legal notices. | Q-SYS Version 8.0.0