SonicKey decoding from file or network stream – User Guide Version 1.0 06 July 2021
This document gives instructions to use the decode command line tool to decode (or detect) the SonicKey from an encoded WAV file.
It also provides instructions to decode the SonicKey from a streaming server and client (using ffmpeg) on a Linux host using the same command-line tool.
Prerequisites
- Latest version of Ubuntu Linux
- The following libraries are to be installed:
a. libsndfile
b. libfftw3
c. libfftw3f
d. llibzita-resampler
e. libcurl - Latest version of ffmpeg package (Version 4.2.4 is used for testing)
- In order to use the decode command-line tool, an API key is required from SonicData.
- In order to view the history of SonicKey detection events on the SonicData Portal ( https:// portal.sonicdata.com ) you need login credentials from SonicData.
- Internet connectivity is required to retrieve the metadata associated with the decoded SonicKey from the SonicData portal.
Decoding SonicKey from file
The following command will decode any SonicKeys present in the given input file and also fetches the metadata associated with that SonicKey from the SonicData portal.
./decode -k APIkey input.wav
- -k APIkey is the API that must be obtained from SonicData. This API key is associated with your login credentials to the SonicData portal.
- The decode tool will print the detected key and try to fetch the metadata associated with the key from SonicData portal. It will print the metadata in the JSON format.
The following is a typical command-line invocation and result from the tool:
./decode -k 60d469319d858b17fxxxxxxx /Sonic/musicbox.wav
2021 Jun 25, 12:44:59: Contacting Sonic Portal with detected key: YSIvTRhr3LM
{
“sonicKey”:
{
“contentCreatedDate”:”2021-03-16T07:18:43.000Z”,
“status”:true,
“sonicKey”:”YSIvTRhr3LM”,
“owner”:”9ab5a58b-09e0-46ce-bb50-1321d9xxxxxx”
“encodingStrength”:10,
“contentType”:”audio/x-wav”,
“contentDescription”:””,
“contentDuration”:45.43421768707483,
“contentSize”:8015004,
“contentFilePath”:”storage/uploads/9ab5xxxx-09e0-46ce-bb50- 1321d92xxxxx/encodedFiles/zqm48d19kmbopeqi-musicbox.wav”,
“contentFileType”:”audio/x-wav”,
“contentEncoding”:”PCM, 44100Hz, undefined, 352800ch”,
“contentSamplingFrequency”:”44100Hz”, “isrcCode”:””,
“iswcCode”:””, “tuneCode”:””,
“contentName”:”Musicbox”,
“contentOwner”:”ArBa-New”,
“contentValidation”:true,
“contentFileName”:”zqm48d19kmbopeqi-musicbox.wav”,
“contentQuality”:”Reasonable”,
“license”:”082e0d36-4bd0-45fe-a969-9a53xxxxxxxx”,
},
“detectionTime”:”2021-06-25T07:14:59.721Z”,
}
Repeating key: YSIvTRhr3LM
Repeating key: YSIvTRhr3LM
Repeating key: YSIvTRhr3LM
decode: reading /Sonic/musicbox.wav: Stream ended
Note: ./decode -v will print the version details of the tool and exit.
Troubleshooting
- If the API key is wrong, you will not be able to fetch metadata from SonicData Portal. In this case, the following error will be displayed:
Unexpected response code from sonic portal: 403 - If the file is not SonicKey encoded (or encoded in some other third party distribution channels), the following error message will be displayed:
Unexpected response code from sonic portal: 404 - The tool will accept WAV files with various sample rates and bit depths such as 16, 24 and 32 bits. By default the tool is expecting a sample rate of 44100Hz. If the input file is of higher sample rate (e. g. 48000Hz), it may be required to increase the internal buffering used by the tool with the -b command line argument as follows.
./decode -b 2 -k APIkey input.wav
-b is the parameter specifying the amount of buffering to be used at the client side. Default value is 1. Valid range is 1 – 3. The larger this value, the more number of media samples will be buffered from the input for decoding.
WAV streaming server on local host using FFMPEG
The network streaming mode of operation is most desirable when the key detection is performed on a network stream such as internet radio stations. This mode is also usable if the input file size is more than a few gigabytes.
Use this command to start the server:
ffmpeg -re -i input.wav -ar 44100 -f rtp rtp://127.0.0.1:1234
Note: This is a single line command without any line breaks.
input.wav is the WAV file, already encoded with a SonicKey.
127.0.0.1:1234 is the IP address and port used. Note that localhost address 127.0.0.1 is used for this guide. This can be any IP address on LAN or Internet as long as it is accessible from the client.
Once the above command is entered, the following will be the output:
ffmpeg version 4.2.4-1ubuntu0.1 Copyright (c) 2000-2020 the FFmpeg developers built with gcc 9 (Ubuntu 9.3.0-10ubuntu2)
configuration: –prefix=/usr –extra-version=1ubuntu0.1 –toolchain=hardened –libdir=/usr/lib/x86_64-linux-gnu –incdir=/usr/include/x86_64-linux-gnu — arch=amd64 –enable-gpl –disable-stripping –enable-avresample –disable-filter= resample –enable-avisynth –enable-gnutls –enable-ladspa –enable-libaom –enable-libass –enable-libbluray –enable-libbs2b –enable-libcaca — enable-libcdio –enable-libcodec2 –enable-libflite –enable-libfontconfig — enable-libfreetype –enable-libfribidi –enable-libgme –enable-libgsm –enable-libjack –enable-libmp3lame –enable-libmysofa –enable-libopenjpeg –enable-libopenmpt –enable-libopus –enable-libpulse –enable-librsvg –enable-librubberband –enable-libshine –enable-libsnappy –enable-libsoxr –enable-libspeex –enable-libssh –enable-libtheora –enable-libtwolame –enable-libvidstab –enable-libvorbis –enable-libvpx –enable-libwavpack –enable-libwebp –enable-libx265 –enable-libxml2 –enable-libxvid –enable-libzmq — enable-libzvbi –enable-lv2 –enable-omx –enable-openal –enable-opencl — enable-opengl –enable-sdl2 –enable-libdc1394 –enable-libdrm –enable-libiec61883 –enable-nvenc –enable-chromaprint –enable-frei0r –enable-libx264 –enable-shared
libavutil 56. 31.100 / 56. 31.100
libavcodec 58. 54.100 / 58. 54.100
libavformat 58. 29.100 / 58. 29.100
libavdevice 58. 8.100 / 58. 8.100
libavfilter 7. 57.100 / 7. 57.100
libavresample 4. 0. 0 / 4. 0. 0
libswscale 5. 5.100 / 5. 5.100
libswresample 3. 5.100 / 3. 5.100
libpostproc 55. 5.100 / 55. 5.100
Guessed Channel Layout for Input Stream #0.0 : stereo Input #0, wav, from ‘raga-wm.wav’:
Duration: 00:03:25.08, bitrate: 1536 kb/s Stream #0:0: Audio: pcm_s16le ([1][0][0][0] / 0x0001), 48000 Hz, stereo, s16, 1536 kb/s
Stream mapping: Stream #0:0 -> #0:0 (pcm_s16le (native) -> pcm_mulaw (native)) Press [q] to stop, [?] for help Output #0, rtp, to ‘rtp://127.0.0.1:1234’: Metadata: encoder : Lavf58.29.100 of 45 51
Stream #0:0: Audio: pcm_mulaw, 44100 Hz, stereo, s16, 705 kb/s
Metadata:
encoder : Lavc58.54.100 pcm_mulaw
SDP:
v=0
o=- 0 0 IN IP4 127.0.0.1
s=No Name
c=IN IP4 127.0.0.1
t=0 0
a=tool:libavformat 58.29.100
m=audio 1234 RTP/AVP 97
b=AS:705
a=rtpmap:97 PCMU/44100/2
size= 9860kB time=00:01:53.02
bitrate= 714.6kbits/s speed= 1x
Please take a special note of the part highlighted above in red. This is the streaming parameters of the server, printed in a format specified by SDP protocol. Please copy and paste that part and save it in a file named wavestream.sdp. This file is required at the client side. The client side uses this SDP file to understand the IP address of the server as well as the streaming parameters used by the server. A sample of this SDP formatted file is shared in the link provided above.
WAV streaming client on local host using FFMPEG & SonicKey decoding
While the server is running as shown above, on another terminal, please execute the following command to start the streaming client and SonicKey decoder:
ffmpeg -hide_banner -loglevel error -protocol_whitelist file,rtp,udp -i wavstream.sdp -y -f wav pipe:1 | ./decode -k APIkey -b 1 stdin
Note: This is a single line command without any line breaks.
In the command above, wavstream.sdp is the server details (its IP address as well as streaming parameters).
- -k APIkey is the API that must be obtained from SonicData. This API key is associated with your login credentials to the SonicData portal.
- -b 1 is the parameter specifying the amount of buffering to be used at the client side. Default value is 1. Valid range is 1 – 3. The larger this value, the more media samples will be buffered from the stream for decoding. The larger this value, the higher will be the accuracy. Obviously, the larger this value, the more time it will take for buffering.
- The decode tool listens to the stream and buffers data from the stream for a fixed time and then proceeds to decode the collected data. The decoded SonicKey is printed. This process is repeated until the stream is ended.
Troubleshooting
- The above instructions are for streaming a WAV format audio file. Other formats can be easily supported by adjusting corresponding FFMPEG parameters at the server. The SDP file must be recreated and copied/transferred to the client side if you change any server side parameters.
- Please make sure the SDP file you create is a plain text file with exactly those lines copy pasted from the server output (see above). A sample SDP file can be downloaded from the link given at the beginning of this document.
- The server will stream the file as long as the normal playback time of the input WAV file. The client side will wait till streaming is started from the server side. It will stop a free seconds after the streaming from the server is ended.
- If the API key is wrong, you will not be able to fetch metadata from SonicData Portal. In this case, the following error will be displayed:
Unexpected response code from sonic portal: 403 - If the file is not SonicKey encoded (or encoded in some other third party distribution channels), the following error message will be displayed:
Unexpected response code from sonic portal: 404
Do you need help?
Email our Support Team or use our enquiry form here