Active Audio Android Manual

Instreamatic offers consumers the power of a voice command while listening to a digital radio stream. Users can say 'Hey, Radio' and ask to open a webpage, show directions, request a promo code, and more. The ad will deliver an appropriate target action.

To fully enable the App, microphone access permission needs to be activated to your App manifest. You can learn more about how to do this via the following link:

Example Manifest

Please note that the application must be developed as a foreground service. And the foreground service must be launched while the activity is visible. Microphone access must be declared for foreground service as well. Please see the link below for reference:

https://developer.android.com/topic/libraries/architecture/workmanager/advanced/long-running#declare-foreground-service-types-manifest

For an actual example of foreground service, please click HERE

(Please turn off the AdBlocker to access the repository)

Project Configuration

repositories {
   jcenter()
   mavenCentral()
   maven {
       url 'http://instreamatic.com/nexus/repository/maven-public'
   }
}
ext {
   admanVersion = '9.2.2'
   serVersion = '6.15.0'
   admanEmbdVersion = '1.1.1'
   admanUWphraseVersion = '1.0.0'
}
dependencies {      
    api 'com.instreamatic:adman-android:' + project.ext.admanVersion + '@aar'
    api 'com.instreamatic:adman-android-view:' + project.ext.admanVersion + '@aar'
    api 'com.instreamatic:adman-android-voice:' + project.ext.admanVersion + '@aar'
    api 'com.sensory.speech.snsr:tnl:'+ project.ext.serVersion +'@aar'
    api 'com.instreamatic.embedded:phrase-spot:' + project.ext.admanEmbdVersion + '@aar'
    api 'com.instreamatic.embedded:voice-recognition-embedded:' + project.ext.admanEmbdVersion + '@aar'
    api 'com.instreamatic:adman-android-module-wphrase:' + project.ext.admanUWphraseVersion + '@aar'
}
android {
   ...
   packagingOptions {
       exclude 'META-INF/DEPENDENCIES.txt'
       exclude 'META-INF/LICENSE.txt'
       exclude 'META-INF/NOTICE.txt'
       exclude 'META-INF/NOTICE'
       exclude 'META-INF/LICENSE'
       exclude 'META-INF/DEPENDENCIES'
       exclude 'META-INF/notice.txt'
       exclude 'META-INF/license.txt'
       exclude 'META-INF/dependencies.txt'
       exclude 'META-INF/LGPL2.1'
   }
   
}

Implementation

Create an instance of Adman first

IAdman adman;
adman = new Adman(this, request_builder.build());
AdmanVoice admanVoice = new AdmanVoice(this);
//for recognition on the device
VoiceRecognitionEmbedded voiceRecognition = new VoiceRecognitionEmbedded(this);
voiceRecognition.addModel("assets/models/large_instrmtc_ovr25_enUS.snsr", LanguageCode.ENGLISH_US);
admanVoice.setVoiceRecognition(voiceRecognition);
adman.bindModule(admanVoice);

Then, set up ad request parameters. You can use the same SDK installation for both Voice Ads and Active Audio.

Voice Ads parameters example

AdmanRequest.Builder request_builder = new AdmanRequest.Builder()
                .setSiteId(1249)
                .setRegion(Region.GLOBAL)
                .setType(Type.VOICE);  

Active Audio parameters example

AdmanRequest.Builder request_builder = new AdmanRequest.Builder()
                .setSiteId(1976)
                .setRegion(Region.GLOBAL)
                .setType(Type.VOR);

If you need to switch between Voice Ads and Active Audio ads, add the following when updating the request parameters

adman.updateRequest(request_builder, true);

Usage example:

AdmanRequest.Builder request_builder = new AdmanRequest.Builder()
                .setSiteId(1976)
                .setRegion(Region.GLOBAL)
                .setType(Type.VOR)
 adman.updateRequest(request_builder, true);

This approach to Active Audio must be used when you are going to play the ad with Instreamatic SDK. If you are going to play it with your own player or insert it into a stream, please see below for detailed instructions.

You can use the default approach for Voice Ads though.

Adding on-device recognition models

Wake word model (Hey, radio): spot_hey_radio_enUS.snsr

On-device recognition models (separate from the wake word):

List of available models for on-device recognition (more to come):

Language	Language Code	Filename
en-US	ENGLISH_US	large_instrmtc_ovr25_enUS.snsr
ru-RU	RUSSIAN	large_instrmtc_ovr50_ruRu.snsr
de-DE	GERMAN	large_instrmtc_ovr50_deDE.snsr

Implementation example:

WPhraseModule wphraseModule = new WPhraseModule(this);
wphraseModule.addListener(this); //this implements WphraseEvent.Listener
wphraseModule.addModel("assets/models/spot_hey_radio_enUS.snsr", LanguageCode.ENGLISH_US);
adman.bindModule(wphraseModule);

If you want to add more models for on-device recognition, add one more VoiceRecognitionEmbedded::addModel with another model.

Ad Request and Playback

This approach to Active Audio must be used when you are going to play the ad with Instreamatic SDK. If you are going to play it with your own player or insert it into a stream, please see below for detailed instructions.

You can use the default approach for Voice Ads though.

Ad Request and Playback for Voice Ads:

//App is started. 
//You are preloading ad at the start of the session
//After the init of the SDK you are preloading an ad:
adman.preload();
//wait for an ad placement.
//For example it's a pre-roll and 'play' button is pressed:
adman.sendCanShow();
//Here you will need to check if there is an ad available for playback
//If the state of Adman is AdmanEvent.Type.READY then ad must be played
adman.play();
//if there is no ad available, return listener to a content and try requesting another ad

This is just a single use-case. You can request an ad at another event, but please keep the above sequence unchanged.

Ad Request and Playback for Active Audio:

adman.start();

If your request parameters were set for Active Audio, the above method will request an ad and then play it right away.

Please find the general usage example HERE

Active Audio Request and Playback for server side in-stream insertion

First of all, you need to request an ad from our Ad Server. It can be done via VAST-Tag:

https://x3.instreamatic.com/v5/vast/1976?microphone=1&type=vor&device_id=<gaid/idfa>&gender=<gender>&age=<age>&ip=<ip>&user_id=<userid>&user_agent=<useragent>

Where:

Parameter Name	Description
user_id	Optional user identifier. You can send us your in-app identifıers for better targetıngç
ip	ip address for geo-targeting
gender	Gender parameter for targeting
age	Age parameter for targeting in min-max format
device_id	Advertising identifier. It's possible to put idfa or gaid there.
user_agent	UserAgent of the client application

Example:

https://x3.instreamatic.com/v5/vast/1976?microphone=1&type=vor&device_id=6ce55d7e-f871-4553-8f99-d195f86b0148&gender=F&age=35-40&ip=88.227.61.31&user_id=123567&user_agent=Mozilla/5.0%20(Windows%20NT%206.1;%20Win64;%20x64;%20rv:47.0)%20Gecko/20100101%20Firefox/47.0x3.instreamatic.com

Instreamatic VOR Ad can be identified by the following values in the VAST Document:

• “instreamatic” in the <AdSystem> tag;

• “![CDATA[ vor ]]” in the “Type” extension

The combination of the two values above indicates the VOR Ad.

The Audio Ad can be found in the <MediaFiles> section of the VAST Document. This is the part for in-stream insertion.

Example:

<MediaFiles>
<MediaFile id="mp3_192" delivery="progressive" type="audio/mpeg" bitrate="192000" codec="mpeg" maintainAspectRatio="false" scalable="true" width="1" height="1">
<![CDATA[ https://dztk6yq65a9he.cloudfront.net/static/creative/audio/D6/30BBAF.mp3 ]]>
</MediaFile>
<MediaFile id="aac_32" delivery="progressive" type="audio/aac" bitrate="32000" codec="" maintainAspectRatio="false" scalable="true" width="1" height="1">
<![CDATA[ https://dztk6yq65a9he.cloudfront.net/static/creative/audio/A8/B775BB.aac ]]>
</MediaFile>
<MediaFile id="aac_64" delivery="progressive" type="audio/aac" bitrate="64000" codec="" maintainAspectRatio="false" scalable="true" width="1" height="1">
<![CDATA[ https://dztk6yq65a9he.cloudfront.net/static/creative/audio/E6/9F2629.aac ]]>
</MediaFile>
<MediaFile id="mp3_128" delivery="progressive" type="audio/mpeg" bitrate="128000" codec="mpeg" maintainAspectRatio="false" scalable="true" width="1" height="1">
<![CDATA[ https://dztk6yq65a9he.cloudfront.net/static/creative/audio/5A/6FA9A1.mp3 ]]>
</MediaFile>
<MediaFile id="m4a_32" delivery="progressive" type="audio/mp4" bitrate="32000" codec="mp4a.40.2" maintainAspectRatio="false" scalable="true" width="1" height="1">
<![CDATA[ https://dztk6yq65a9he.cloudfront.net/static/creative/audio/23/C99567.mp4 ]]>
</MediaFile>
<MediaFile id="m4a_64" delivery="progressive" type="audio/mp4" bitrate="64000" codec="mp4a.40.2" maintainAspectRatio="false" scalable="true" width="1" height="1">
<![CDATA[ https://dztk6yq65a9he.cloudfront.net/static/creative/audio/4F/C20AB8.mp4 ]]>
</MediaFile>
</MediaFiles>

It’s possible to get audio files in different codecs: MP3 192kbps/128kbps, AAC 32kbps/64kbps, m4a 32kbps/64kbps.

Before playing an ad, the XML response must be converted to an array of bytes.

At the ad placement with Active Audio, call the following method:

adman.setVASTBytes(byte[] byteArray, boolean startPlaying)

Instreamatic SDK will start listening to the wake-word and you'll receive the START_DETECT event.

The SDK will wait for the wake-word while the ad is playing. You can retrieve the ad duration using the below method (if needed):

VASTInline vastInline = adman.getCurrentAd();
int duration = vastInline != null ? vastInline.duration : 0;

If SDK will catch the wake-word, it will enable the mic for command recognition. STOP_DETECT event will be reported.

Then the SDK will send the START event from AdmanVoice-module. This event must be used as an indication of the moment when the stream volume must be lowered.

At the end of the recognition session, the SDK will send the STOP event. This event must be used as an indication of the moment when the stream volume must be turned back on.

Don’t forget to call adman.sendCanShow() on all the ad placements even if there is no ad to play.