Alexa.Gadget.MusicData Interface (Beta)

Note: Submit your skill and see it come to life.

Note: On December 31, 2021, we paused support for third-party device makers working with Alexa Gadgets, while we work to create an even better developer and customer experience. Please stay tuned to the Amazon developer portal for updates. In the interim, please visit the landing pages for Alexa Voice Service, Alexa Connect Kit, and Alexa Skills Kit to discover ways you can provide new customer experiences with voice.

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.

Note: Each directive and event is a compilation of three separate .proto files: a header, a payload, and a file that combines the two. You can download the .proto files from the Alexa Gadgets Sample Code GitHub repository. In this topic, the .proto files combine all fields into one file for descriptive purposes.

Supporting this interface
Directives
- Tempo directive

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`