# Song Objects

An array of JSON song objects is required by AmplitudeJS. This directs AmplitudeJS to the metadata and information necessary for playing the audio.

A basic song object has the following keys:

• name = The name of the song
• artist = The song's artist
• album = The song's album ( Also used to determine album changes in an environment where multiple albums are used on the page)
• url = The URL to the song. This is most important. (Soundcloud URLs discussed later)
• cover_art_url = The URL to the song's cover art.
• live = Set to true for a URL that is a live audio source.

The only actually required key is the url so AmplitudeJS can play the song.

The song object can include any number of keys which can be displayed anywhere on the page. You can make up a key name if you want like

	{
		"name": "Song Name 3",
		"artist": "Artist Name",
		"album": "Album Name",
		"url": "/song/url.mp3",
		"cover_art_url": "/cover/art/url.jpg",
		"made_up_key": "I'm made up completely"
	}

and reference it anywhere on your page using the 'amplitude-song-info' attribute on the element you want to display the data like:

	<span class="made-up-key" amplitude-song-info="made_up_key"></span>

It is important to note that in multiple song environments, the order that you list the songs makes a difference. When utilizing next and previous functionality, AmplitudeJS will iterate over the songs object and go to the next song or the previous song in the list. If you are using AmplitudeJS in a playlist type environment, you will define the order of the songs in the playlist by their individual indexes.

It is also important to note how songs are indexed. Like in almost all programming, indexes start at 0. So when you are setting up multiple play/pause functions or song status sliders that relate to an individual song or playlists, the indexes are used. For example, the song above named "Song Name 1" would have an index of 0, "Song Name 2" would have an index of 1, and so on.

# Special Keys

# Song Specific Visualization

With the introduction of Amplitude FX Song Visualizations, you can apply a specific visualization to a song (visualizations are discussed later in the docs). Once you register a visualization, you can assign it to a song like this:

	{
		"name": "Song Name 3",
		"artist": "Artist Name",
		"album": "Album Name",
		"url": "/song/url.mp3",
		"cover_art_url": "/cover/art/url.jpg",
		"made_up_key": "I'm made up completely",
		"visualization": "your_visualization_key"
	}

Now when the song plays, the visualization you specify will be played in all visualization elements.

# Time Callbacks

Like other callbacks in AmplitudeJS (discussed in the Callbacks section of the docs), you can do specific time based callbacks on any song. These are a little complicated, but extremely powerful and allow you to do things like display lyrics or show images at certain points. Let's take an individual song object and add a callback at 1 second into the song 1 minute 30 seconds into the song and 1 minute 50 seconds into the song.

We first start with our individual song object and add a time_callbacks object:

	{
		"name": "Song Name 3",
		"artist": "Artist Name",
		"album": "Album Name",
		"url": "/song/url.mp3",
		"cover_art_url": "/cover/art/url.jpg",
    		"time_callbacks": {
			
    		}
	}

Within that time_callbacks object, we can add functions that get called at a certain "second" in the song. The "second" that we want the callback to run will be the key of the object. For our example, our song will look like this:

	{
		"name": "Song Name 3",
		"artist": "Artist Name",
		"album": "Album Name",
		"url": "/song/url.mp3",
		"cover_art_url": "/cover/art/url.jpg",
    		"time_callbacks": {
      			1: function(){
        			console.log( "1 second into the song" )
      			},
      			90: function(){
        			console.log( "1 minute 30 seconds into the song" );
      			},
      			110: function(){
        			console.log( "1 minute 50 seconds into the song" );
      			}
    		}
	}

Now when we get to each of the timestamps, we can run a function. This is extremely powerful for maybe displaying lyrics, or advertisements, or just having flexible control over the audio!