Broadcastify-Calls-API

Broadcastify Calls is different from regular broadcastify feeds as the calls platform captures every single call on a conventional or trunked system, as individual call files, and makes those calls available in real time and in archives. The Broadcastify Calls platform is not intended to replace regular Broadcastify audio streams at this time, but to supplement them, and we will eventually create Broadcastify audio streams from the Broadcastify Calls platform.

Broadcastify Calls makes available to call ingest providers ALL calls they send to us, but limits public access to calls covered by our Feed Provider Terms of Service

Broadcastify Calls Features includes:

30 day retention
duplicate call handling
Live Call Playback
Playlists Playback
tight integration with the RadioReference database
call and source detailed statistics

See the current interface here: https://www.broadcastify.com/calls/

You can submit an application to send calls here: https://www.broadcastify.com/apply/calls

Development Process

Developer contacts broadcastify at support@broadcastify.com with details and intentions
Developer is issued an API Key and System ID for a test system to use in the development environment
Developer codes some awesome implementation to use the Broadcastify Calls API documented below

API Process

Application verifies that proper time sync is installed, configured, running, and time is properly synched on the host computer.
Application records a call and associated metadata (talkgroup, frequency, site, source ID)
Application converts call audio to AAC Audio (*.m4a) or MP3 Audio (*.mp3)
Application calls the Broadcastify Calls API to register the clip, and an upload URL is returned
Application uploads the call to Broadcastify's storage servers with an HTTP PUT request

Upload API

Apply for an API Key and System ID

An API key and unique system ID identifier is required for every uploaded system. API Keys and System Identifiers will be different between development and production.

You can submit an application to send calls here: https://www.broadcastify.com/apply/calls

Convert Audio to M4A or MP3

Convert to M4A AAC Audio

Example:

ffmpeg -i "${basename}.wav"  -c:a libfdk_aac -b:a 32k -cutoff 18000 "${basename}.m4a

Convert to MP3 MPEG Audio

Accepted Standards are one of the following:

32 kb/s, Mono, Sample of 22050 Hz, CBR (Constant Bit Rate)
16 kb/s, Mono, Sample of 22050 Hz, CBR (Constant Bit Rate)

Get the duration of the audio clip

ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "${basename}.m4a

Register the Clip and get the Upload URL

This is a RFC1867 multipart/form-data POST request to the API Endpoint.

curl -s https://api.broadcastify.com/call-upload-dev  
  -F "apiKey=${APIKEY}" 
  -F "systemId=${SYSTEMID}"
  -F "callDuration=${duration}" 
  -F "ts=${timestamp}" 
  -F "tg=${tg}" 
  -F "src=${src}" 
  -F "freq=${freq}"

URL for Development: https://api.broadcastify.com/call-upload-dev
URL for Production: https://api.broadcastify.com/call-upload 

apiKey		= API Key 
systemId 	= Unique System ID Assigned to this call ingest system (paired with API Key Assignment)
callDuration 	= duration of the call in seconds (float number)
ts 		= call START timestamp in epoch seconds (unix timestamp)
tg 		= call talkgroup 
                  Trunked: Call Talkgroup in decimal format. If patch, a comma delimited string of 
		            talkgroups with Patch ID listed first
                  Conventional: Call Frequency Slot ID.  These have to be predefined by the administrator
src 		= call source decimal ID (unit ID)
freq 		= call frequency (float number - trunked and conventional call upload)
enc		= [optional] encode type m4a|mp3 - default is m4a (aac audio)

Example Trunked Call in Development (API Key and SID is an example only):

curl -s https://api.broadcastify.com/call-upload-dev 
-F "apiKey=6a1f044b-88c3-11fa-bd8b-12348ab9ccea" 
-F "systemId=34" 
-F "ts=1588168366" 
-F "tg=13012" 
-F "freq=856.4875" 
-F "callDuration=11.4"

Example Conventional Call in Development (API Key and SID is an example only):

curl -s https://api.broadcastify.com/call-upload-dev 
-F "apiKey=6a1f044b-88c3-11fa-bd8b-12348ab9ccea" 
-F "systemId=144" 
-F "ts=1588168361" 
-F "tg=1" 
-F "freq=154.430" 
-F "callDuration=4.3" 
-F "enc=mp3"

Successful return is a single line with a return code followed by a one time use upload URL.

Example: 0 https://upload.hostname.com/uploadPath/oneTimeUseKey

Error return is an error code followed by an error message

Example: 100 NO-API-KEY-SPECIFIED

If we've already received the call from another system, we will reject the duplicate call with:

Return: 1 SKIPPED---ALREADY-RECEIVED-THIS-CALL

Upload the Audio File

m4a aac audio:
curl --write-out %{http_code} --silent --output /dev/null -X PUT -H "Content-Type: audio/aac" 
-T ${basename}.m4a "${uploadURL}"

mp3 mpeg audio:
curl --write-out %{http_code} --silent --output /dev/null -X PUT -H "Content-Type: audio/mpeg" 
-T ${basename}.mp3 "${uploadURL}"

Check the status of your system

Dev:  https://www.broadcastify.com/calls-dev/status/
Prod: https://www.broadcastify.com/calls/status/
      https://www.broadcastify.com/calls/manage/

Test Credentials (Optional)

A test call is available to test a user's issued API Key and SID

DEV: curl -s https://api.broadcastify.com/call-upload-dev -F "test=1" -F "apiKey=APIKEY" -F "systemId=SID"
PROD: curl -s https://api.broadcastify.com/call-upload -F "test=1" -F "apiKey=APIKEY" -F "systemId=SID"

Broadcastify-Calls-API

From The RadioReference Wiki

Contents