Alexa.Gadget.MusicData Interface (Beta)

This interface sends your gadget tempo data for Amazon Music that the Echo device is playing. This interface works with Amazon Music only; it does not support other music service providers.

If your gadget supports this interface, it will receive two Tempo directives per song: one at the beginning of the song and one at the end of the song. The tempo data that is provided at the beginning of the song is the average beats per minute for the song. At the end of the song, the tempo data provided is zero, to indicate that the song has ended.

Tempo data is sent to the gadget even when Amazon Music is muted.

Supporting this interface

To support this interface, the gadget must respond to the Echo device's Discover directive with a Discover.Response event that includes the following entry in its array of Capabilities:

{
   "type": "AlexaInterface",
   "interface": "Alexa.Gadget.MusicData",
   "version": "1.0",
   "configurations": {
      "supportedTypes":[
       {
          "name":"tempo"
       }
      ]
    }
}

Directives

This interface includes one directive: Tempo, as described next.

Tempo directive

This directive provides music tempo to your gadget. The .proto file contents are as follows:

message TempoDirectiveProto {
   Directive directive = 1;
   message Directive {
      alexaGadgetMusicData.TempoDirectivePayloadProto payload = 2;
      header.DirectiveHeaderProto header = 1;
   }
}

message DirectiveHeaderProto {
   string namespace = 1; 
   string name = 2; 
   string messageId = 3; 
   string dialogRequestId = 4;      
}

message TempoDirectivePayloadProto {
   int32 playerOffsetInMilliseconds = 1;
   repeated TempoData tempoData = 2;
   message TempoData {
      int32 startOffsetInMilliseconds = 2;
      int32 value = 1;
   }
}

TempoDirectiveProto

The fields in this message are as follows:

Field Description Type
directive Contains a complete Tempo directive. Directive

Directive

The fields of the message are as follows:

Field Description Type
header Contains the header for this directive. DirectiveHeaderProto
payload Contains the payload for this directive. TempoDirectivePayloadProto

DirectiveHeaderProto

The fields of the message are as follows:

Field Description Type
namespace The namespace of this directive, which is Alexa.Gadget.MusicData. string
name The name of this directive, which is Tempo. string
messageId An ID that uniquely defines an instance of this directive. This string can be empty. string
dialogRequestId A unique ID that correlates this directive with a specific voice interaction from a user. You can ignore this field. string

TempoDirectivePayloadProto

The fields of the message are as follows:

Field Description Type
playerOffsetInMilliseconds Where the audio player currently is in its stream, in milliseconds. int32
tempoData An array of TempoData objects that each contain a music tempo value in units of beats-per-minute (BPM) and the offset, from the start of the song, at which the specified tempo value goes into effect. Array of TempoData

TempoData

The fields of the message are as follows:

Field Description Type
startOffsetInMilliseconds The start offset of the value from the start of the song, in milliseconds.

To determine how to sync to a song, use startOffsetInMilliSeconds minus playerOffsetInMilliseconds.

For example, say your gadget receives tempo data with playerOffsetInMilliseconds = 7000 and startOffsetInMilliSeconds = 9000. In this case, your gadget can calculate that the data it is receiving is 2000 ms into the song.


If the tempo at startOffsetInMilliseconds is zero or if playerOffsetInMilliseconds is greater than or equal to startOffsetInMilliseconds, the gadget should process the data immediately.
int32
value Music tempo value in units of beats per minute. A value of zero indicates the end of the song. int32

Last updated: Mar 31, 2022