Version 1.0, 08 July 2021
This document gives instructions to use the encode command line tool to encode WAV format files with a SonicKey.
Note that the binary version of SonicData tools only supports WAV file format. It supports all variants of WAV files such as 16bit, 24bit or 32bit and all common sample rates such as 44100HZ and 48000Hz.
Prerequisites
- Latest version of Ubuntu Linux
- The following libraries are to be installed:
a. libsndfile
b. libfftw3
c. libfftw3f
d. llibzita-resampler
e. libcurl - In order to use the encode command-line tool, an API key as well as a License key is required from SonicData.
- In order to view the SonicKey metadata details on the SonicData Portal you need login credentials from SonicData.
- Internet connectivity is required to post the metadata associated with the detected SonicKey from the SonicData portal.
Encoding a WAV file with SonicKey
The following command will fetch a SonicKey from SonicData portal and encode the given WAV file with it. Upon successful encoding, the SonicKey and given metadata will be uploaded to SonicData portal which you can view by logging in onto the portal.
$./encode [-v] [-k APIkey (mandatory)] [-l Licensekey (mandatory)] [-n contentName] [-d contentDescription] [-o contentOwner/artist] [-q contentQuality] [-t contentType (1=Music, 2=Others)] [-r ISRC] [-w ISWC] [-u Tunecode] [-a AdditionaMetadata (any string)] [-h AlgorithmHardness] infile outfile
- -v
Will display the version details of the tool and exit. - -k APIkey
A string that is the API key that must be obtained from SonicData. This API key is associated with your login credentials to the SonicData portal. This is a mandatory parameter. - -l Licencekey
A string that is the License key that must be obtained from SonicData. This License key is associated with your login credentials to the SonicData portal. This is a mandatory parameter. - -n contentName
A string that is the name of the audio input. In case of music tracks, this will usually be the song name. - -d contentDescription
A string that is the description of the track. - -o contentOwner/artist
A string using which you can specify the owner of the track or the details of artist or recording company etc. - -q contentQuality
A string that describes the quality of the audio track (E.g. “Live recording with a bit of noise”) - -t contentType
An integer with possible values of 1 to indicate Music and 2 to indicate any other type of audio. - -r ISRC
A string that is the ISRC of the input audio track. If you specify the contentType as Music (value 1), then either ISRC code or ISWC code or Tunecode (any one) is mandatory. - -w ISWC
A string that is the ISWC of the input audio track. If you specify the contentType as Music (value 1), then either ISRC code or ISWC code or Tunecode (any one) is mandatory. - -u Tunecode
A string that is the Tunecode of the input audio track. If you specify the contentType as Music (value 1), then either ISRC code or ISWC code or Tunecode (any one) is mandatory. - -a AdditionaMetadata
Any additional details that you want to associate with this track. This can be an arbitrary length string. Please make sure that proper escape characters will be required if you use special characters on the command line. - -h AlgorithmHardness
This is an optional parameter, which is an integer value between 1-100. This controls the hardness (strength) of encoding. The more this value, the more robust and error resilient will be the encoding. However, any value greater than 30 can affect the audio quality. If you omit this argument, the default value of 15 will be assumed by the tool. If you intend to use the encoded audio in a noisy environment and still want the key detection to be reliable, a value of 20-25 is recommended. Otherwise leave it at the default value of 15. - infile
A string that is the full path to input file. This is a mandatory parameter. - outfile
A string that is the full path to output file. This is a mandatory parameter.
Command line parameter errors
In case of any errors in parameters specified, the tool will guide you with proper error messages. Invoking the tool without any command line argument will print the above usage information message.
The following is a typical command-line invocation and result from the tool:
$./encode -k 60d469319d858b17fbxxxxxc -l 159bb263-b265-451a-ae3d-0d789dxxxxxx -n “Musicbox demo” -d “This is description about the track” -o “Owner or artist details” -q “Good” -t 1 -u “12345678aa” -a “Additional Metadata Test” -h 10 / home/sonic/musicbox.wav /home/sonic/musicbox-wm.wav
Fetched SonicKey: w3jPt1s0McW
Input audio file: /home/sonic/musicbox.wav
Duration of input: 0 min, 45 sec
Sample rate of input: 44100
Number of channels of input: 2
Watermark sonickey: w3jPt1s0McW
Strength of watermarking algorithm: 10
Processing finished.
{
“contentCreatedDate”:”2021-06-30T12:52:12.108Z”,
“status”:true,
“downloadable”:false,
“encodingStrength”:10,
“contentDuration”:45,
“contentSize”:8015004,
“contentValidation”:false,
“contentDescription”:”This is description about the track”,
“contentEncoding”:”PCM, 16bits, 2channels”,
“contentFileName”:”musicbox”,
“contentFilePath”:”/home/sonic/musicbox.wav”,
“contentFileType”:”WAV”,
“contentName”:”Musicboxdemo”,
“contentOwner”:”Owner or artist details”,
“contentSamplingFrequency”:”44100″,
“contentType”:”Music”,
“tuneCode”:”12345678aa”,
of 41 51 “additionalMetadata”:
{
“message”:”Additional Metadata Test”
},
“sonicKey”:”w3jPt1s0McW”,
“channel”:”BINARY”,
}
Successfully posted encoded SonicKey and metadata to Sonic Portal
The encoded SonicKey as well as its associated metadata (as printed above at the end of processing) can be viewed anytime by logging into your account at SonicData portal.
Troubleshooting
- The tool will process only WAV files. Behaviour is undefined on other file formats.
- All command line arguments must be properly escaped if there are any special characters. All usual rules of Linux bash shell command line tools are applicable here.
- If the API key is wrong, you will not be able to post metadata to SonicData Portal. In this case, the following error will be displayed:
Unexpected response code from sonic portal: 403 - If the License key is wrong, you will not be able to post metadata to SonicData Portal. In this case, the following error will be displayed:
Unexpected response code from sonic portal: 400
Known limitations
- The industry codes (ISRC, ISWC andTunecode) format is not validated in this version of the tool. This will be added in later updates.
- As mentioned above, the tool only supports WAV file format. It does support all variants of WAV formats though.
Do you need help?
Email our Support Team or use our enquiry form here