SDK

Beeping Sdk Unity

BEEPING

Beeping Unity SDK

Tested on Unity 5.6.0f3 Personal (64 bits) OSX & Windows

Although the plug-in has been created with Unity 5.6 it should be possible to use it in any Unity > 5.0. If when you open the project the assets and scene are not loaded correctly, the objects can be loaded manually.

The Beeping Unity plug-in has been built over the Unity Native Audio Plugin SDK: https://docs.unity3d.com/560/Documentation/Manual/AudioMixerNativeAudioPlugin.html https://bitbucket.org/Unity-Technologies/nativeaudioplugins


Compatibility

Although in Unity by default the plug-ins are portable, the beeping SDK plug-in includes a c++ native non-managed plug-in that has been compiled only for the following platforms: android/armv7, android/emulator iOS/universal, windows/32/64 & osx/64. If you are interested in another platform please contact [email protected].


Installation

1. Start Unity

2. Open project folder “beeping-sdk-unity/BeepingCoreUnitySDK/”

3. Open beeping scene:

File -> Open scene… -> Assets/scenes/beeping.unity

Description of the contents of the beeping scene:

  • Mixer:

Assets/mixers/BeepingMixer.mixer*

*If you already have a mixer in your unity project, put BeepingMixer as a new mixergroup, as a child of your master mixer

  • Native plug-ins:
Assets/Plugins/Android/libs/armeabi-v7a/libAudioPluginBeepingCore.so *(android armv7)*
Assets/Plugins/Android/libs/x86/libAudioPluginBeepingCore.so *(android x86 emulator)*
Assets/Plugins/iOS/AudioPluginBeepingCore.a *(static universal iOS)*
Assets/Plugins/iOS/AudioPluginInterface.h *(header needed for iOS xcode build, see below)*
Assets/Plugins/x86/AudioPluginBeepingCore.dll *(windows 32 bits)*
Assets/Plugins/x86_64/AudioPluginBeepingCore.dll *(windows 64 bits)*
Assets/Plugins/x86_64/AudioPluginBeepingCore.bundle *(OSX 64 bits)*
  • Scripts C#:
Assets/scripts/BeepingUnity.cs *(Main SDK script that interfaces with the native plug-ins and deals with Microphone input)*
Assets/scripts/SimpleJSON.cs *(3rd party code to parse JSON http://wiki.unity3d.com/index.php/SimpleJSON#SimpleJSON.cs)*
Assets/scripts/BeepingTest.cs *(Test C# script example of Beeping SDK usage)*

Here it is an example of how it looks the beeping scene once loaded in Unity:

Unity Screenshot

And here when in play mode in the Unity editor:

Unity Screenshot

4. Set Unity Project Audio Settings to the following values:

  • You may change System sample rate to 44100 Hz or 48000 Hz (mandatory for receiving beeps). To change sample rate go to menu bar Edit -> Project Setting -> Audio

  • Best practice is to set DSP Buffer Size in the Audio Manager to Best Performance.

  • You might set the Default Speaker Set to mono (if possible, otherwise it will also work).

5. Choose build settings (platform and features) and run:

File -> Build Settings... -> Build and Run

  • VERY IMPORTANT for iOS (do this after build and before run):

In the generated Xcode-Project open /Classes/UnityAppController.mm

Add the line (line 34):

#include "../Libraries/Plugins/iOS/AudioPluginInterface.h"

In the same file replace line (line 115):

- (void)preStartUnity {}

with

- (void)preStartUnity { UnityRegisterAudioPlugin(&UnityGetAudioEffectDefinitions); }

6. You are done!


Usage example of Beeping Plug-in in a 3rd party app

In Unity editor create a script associated to your scene, in this script (see example below), create your class (BeepingTest) and declare a variable of type BeepingUnity that will be the instance of the Beeping plug-in.

Then in the start function of your class assign the object (beeping plug-in) to your local variable and assign a callback “void OnBeepReceived(int id, int error, string beep_info)” to the OnBeep beeping event that will be triggered when a beeping message is being decoded or has finished decoding.

IMPORTANT!: Before starting the beeping library you need to set your appId, if you don’t have one Your App must request an AppId from our Development Team. You will need this key to initialize the Beeping SDK. Get in touch at [email protected].

You can initialize the beeping SDK with your appid using the setAppId function:
beeping.setAppId("this_is_your_application_id");

Once the callback is set and you have set your appId you can start or stop decoding using the following functions (usually from a button in GUI):

beeping.startListening();
beeping.stopListening();

The callback OnBeepReceived has 3 parameters:

  • int id: contains the id of the message received, it can be:
  1:  beep has been decoded and received from SDK
      e.g. beep received ok and beeping_info parameter then contains a json with the beep metadata
  0:  other beep decoding info received (the actual msg is found in parameter beep_info)
      e.g. when the beeping SDK has found a beep and it is still decoding it
  • int error: contains error code and can be:
  0:  no error
      e.g. when beep has been decoded and it is ok
  1:  error detected (error msg is found in parameter beep_info)
      e.g. when a beep has been decoded with errors due to a transmission problem (noise) or beep not recognized 
           by the beeping back-end
  • string beep_info: contains data received from beeping SDK, the value will depend on previous parameter values.

IMPORTANT: When we successfully detect and retrieve a beep, the callback OnBeepReceived is triggered.
The beep_info string will contain a Beep JSONObject (sample provided below).

Sample Successful Response Beep JSONObject ()
  {
      "type": "url",
      "data": "https://www.youtube.com/watch?v=DiTECkLZ8HM",
      "url": "https://www.youtube.com/watch?v=DiTECkLZ8HM",
      "title": "SPIDER-MAN: HOMECOMING - Official Trailer #2 (HD)",
      "brand": "YouTube",
      "imgSrc": "https://i.ytimg.com/vi/DiTECkLZ8HM/maxresdefault.jpg",
      "ogType": "video",
      "_id": "C9bPJJNtij6JAhKeS",
      "avatar": "https://s3.amazonaws.com/beepingfiles/images/beeping_avatar.png",
      "init": 0,
      "final": 10000,
      "createdAt": "2017-03-22T19:18:45.178Z",
      "updatedAt": "2017-03-22T19:18:45.180Z"
  }

NOTICE: Please be advised that the url field will be deprecated by June 1st 2017. It will be replaced by data field. Both fields will be working until the aforementioned date.

When an error happens while retrieving a beep, it might be because of different reasons, the beep is not found on the server, the appid is not recognized or whatever error. In these cases beeping_info contains a json object (sample provided below) with the error code. Title parameter will be replaced with the error string code and the error message will contain an explanation of the error.

Sample on Beep Error response JSONObject ()
  {
      "title": "error message"
  }

There are also other getter functions available to get quality information about a received beep:

  • Get volume in dBs of received beep, we expect succesful decodings when this value is over -100dBs

public float getReceivedBeepsVolume()

  • Confidence of reliability of the received beep between 0.0 and 1.0 being 1.0 the maximum reliability

public float getConfidence()

(Alpha feature): Sample Successful Response Beep JSONObject () in Offine Mode
  {
      "data": "o7o8r"
  }

We are testing a new feature that allows the Beeping SDK to function offline without data connection. All is required to enable offline mode is to call the following function while initializing the Beeping SDK:

beeping.setOffline();

As shown above in the sample JSONObject, the callback OnBeepReceived responds with just one key-value pair containing a reference_id ("o7o8r"). You can use this reference_id to trigger actions or assets within your app without a data connection.

NOTICE: In offline mode, all dashboard analytics (https://beeping.io) are disabled.

Important Information for Android Developers

Starting Android 5.0 and higher, apps uploaded to the Google Play Store require that the microphone permission is asked to the user ONLY when it is needed, this means that you may want to have the beeping object disconnected from the scene until you need the beeping feature. Once the user grants permission to access the microphone, you may want to connect the beeping object to the scene and call the StartListening() function to set the beeping object in listening mode to decode beeps.


E.g (BeepingTest.cs):

//BeepStoryboard class is a serializable class that will contain info received from each detected beep
[System.Serializable]
public class BeepStoryBoard
{
  public string type;
  public string data;
  public string url;
  public string title;
  public string brand;
  public string imgSrc;
  public string ogType;
  public string _id;
  public string avatar;
  public int init;
  public int final;
  public string createdAt;
  public string updatedAt;
  public string audioSrc;
}

public class BeepingTest : MonoBehaviour {

  BeepingUnity beeping;

  void Start()
  {
    beeping = GameObject.FindObjectOfType (typeof(BeepingUnity)) as BeepingUnity;
    beeping.OnBeep += OnBeepReceived;

    beeping.setAppId("this_is_your_application_id"); //thisisyourapplicationid
    
    //The following methods will be called from a button, or user action, menu, etc. Should not be called 
    //at the Start function of this example because the BeepingUnity object might not be yet initialized.
    //beeping.startListening();
    //beeping.stopListening();
  }

  void OnBeepReceived(int id, int error, string beep_info)
  {
    if (id == 1)
    {
      if (error == 0)
      {
        BeepStoryBoard BS = JsonUtility.FromJson<BeepStoryBoard>(beep_info);
        Debug.Log("beep received ok! " + BS.data);
      }
      else 
      {
        Debug.Log("beep received with error! " + beep_info);
      }
    }
    else if (id == 0)
    {
      Debug.Log("beeping info received: " + beep_info);
    }
  }
}

License

Beeping LLC © (https://beeping.io)