As an end user, when on the dance floor
I should see music notes and flashy colors
So that I am excited about dancing

• Running animation at top
• Some kind of sad thing when they tap a spot not on a dot

As a developer,
When I request a Song's information using GET api/v1/songs?title=<title>

• The Service will first query the Database for a record in the Songs table with the requested title.

• The Service will return the matching Song record in JSON format, example below.

If no record is found
Spotify API Song Search Endpoint - User Story #32

• The Service will have a valid Access Token ready to use (Token Generator - User Story #29)

• The Service will use the Spotify API Search endpoint to look for the requested Song using the original request's params.title. Returning an array of songs in tracks.items

• The Service will first query the Database for records matching spotify_id = tracks.items[0..5].id.

• If a record is returned from one of the spotify_ids. The Service will return that object in JSON. Which will end the Service's workflow.

• If no record is returned. The Service will find the requested song by comparing tracks.items[0..5].name to params.title. Then use the first element it matches with.

• The Service will store the name, id, and url of the matched element to be used in the next step.

• Spotify API Song Search - User Story #32 Complete
  .

Spotify API Audio Analysis Endpoint - User Story #37

• The Service will request Audio Analysis data at GET https://api.spotify.com/v1/audio-analysis/<spotify_id> using the spotify_id from the Song Search response.

• The Service will create a record in the Songs table using the title, spotify_id, url from the Song Search response. Along with the delay, avg_bar_duration, duration, tempo, and time_signature from the Audio Analysis response.

• The Service returns the formatted JSON object indicated below.

{
  spotify_id: '3KzgdYUlqV6TOG7JCmx2Wg',
  title: 'Beyond The Sea',
  url: 'https://open.spotify.com/track/3KzgdYUlqV6TOG7JCmx2Wg',
  duration: 172.48,
  delay: 0.543,
  avg_bar_duration: 1.764,

  tempo: 136.483,

  time_signature: 4
}

• Spotify API Audio Analysis - User Story #37 complete

• Service GET api/v1/songs Endpoint - User Story #8 complete

As an end user, when on the dance floor
I should have my taps registered
So that the app can keep track of my score by counting accurate taps.

As an end user, when on the dance floor
I should have have left and right foot beats distinguished
So that I know which foot goes where.

As an end user, after the dance floor page,
I should see my score as a reflection of my correct steps vs possible correct steps
So that I can know how whether I need to practice more

As an end user, when on the dashboard
I should see a confirmation button
So I can click to confirm my chosen song and dance
In order to move on to the next page with the correct info

As an end user, when on the dance floor
I expect to hear my chosen song begin playing after I click the start button
So that i can practice to music

• Comments only when user hits the step
• Feeback for when the user missed

As a developer,
When I request a Song's Audio Analysis,
In order to create a new Song record with all necessary data for that song,
I'm returned a JSON response with the requested Song's Audio Analysis.
Spotify API Audio Analysis Docs

Song Audio Analysis Request:
Route
GET https://api.spotify.com/v1/audio-analysis/<spotify_id>

Headers
Authorization: Bearer <Access_Token>

Response

{
    "meta": {..},
    "track": {
        "duration": 172.48000,
        "offset_seconds": 0,
        "end_of_fade_in": 0.16853,
        "start_of_fade_out": 163.66005,
        "tempo": 136.483,
        "tempo_confidence": 0.311,
        "time_signature": 4,
        "time_signature_confidence": 0.981,
        "key": 2,
        "key_confidence": 0.262,
        "mode": 0,
        "mode_confidence": 0.394,
    },
    "bars": [
        {
            "start": 0.54307,
            "duration": 1.80943,
            "confidence": 0.500
        },
        {
            "start": 2.35250,
            "duration": 1.74612,
            "confidence": 0.579
        },
 ...]
}

Service will then create a new record in the Song table with the following data:

• spotify_id = The spotify_id used to request the Audio Analysis endpoint
  .
• title = The title of the Song.
  Gathered from the previous Spotify API Song Search request
  .
• url = The Spotify play URL used to play the Song.
  Gathered from the previous Spotify API Song Search request
  .
• delay = Delay between the Song's beginning and the first Bar's beginning.
  Taken from bars[0].start
  .
• avg_bar_duration = Average duration of a Bar.
  Acquired by (sum of bars.duration / bars.count)
  .
• duration = Duration of the Song
  track.duration
  .
• tempo = Tempo of the Song
  track.tempo
  .
• time_signature = Number of beats per Bar
  track.time_signature

As a developer,
I should have a PostgreSQL database,
With a table for Songs,
With each record containing a Song's:

• id
• spotifyId
• title
• url Spotify play URL
• delay delay between the Song's beginning and the first measure's beginning
• avgBarDuration average duration of a bar/measure
• duration duration of the song
• tempo
• timeSignature to identify the number of beats per measure
• dance enumerator to determine what type of dance this song belongs to
• test the db config

As a developer,
When I submit a GET request to the Ballroom-Beats-Service with a Song's title in the params,
In order to receive the Song's beat, tempo, and delay information,
I'm returned the following JSON output representing that Song's info

GET api/v1/songs?title=Beyond The Sea

Happy Path
Status 200

{
spotify_id: 3KzgdYUlqV6TOG7JCmx2Wg
title: Beyond The Sea
url: https://open.spotify.com/track/3KzgdYUlqV6TOG7JCmx2Wg
delay: 0.168 seconds
bar_duration: 1.764
duration: 172.48
tempo: 136.48

timeSignature: 4
}

Sad Path
Status 500

Note:
When a request is submitted, the service will first query the Database to find the requested record.
If no record is found, the Spotify Service will begin: #38

As an end user
When I visit the dashboard
I should click to see a dropdown menu that includes my dance
In order to choose a chance to practice

As an end user
While on the dashboard, once I have selected a dance
I should see a song with a time signature that fits my chosen dance
So that I can practice to a song with the correct beat

Add mock API call
Call object into app
Add values into app where they are currently hard coded

As an end user, When on the dance floor,
I should see the steps stop when the music stops
So that I don't have to dance to no music

As and end user, on the dance floor
I should see the indicators arranged to fit the choreography of the dance I chose
So that I can practice the correct dance

As a developer,
When I search for a Song based on its title using the Spotify API,
In order to retrieve its spotify_id,
I receive a response body that contains the requested Song and its spotify_id
Spotify API Search Docs

Song Search Request:
Route
GET https://api.spotify.com/v1/search

Params
q=<song_title>
type=track

Headers
Authorization: Bearer <Access_Token>

Response

{
  "tracks": {
    "href": "https://api.spotify.com/v1/search?query=beyond+the+sea&type=track&offset=0&limit=20",
    "items": [
      {
        "album": {...},
        "artists": [...],
        "available_markets": [...],
        "disc_number": 1,
        "duration_ms": 172480,
        "explicit": false,
        "external_ids": {..},
        "external_urls": 
         {
          "spotify": "https://open.spotify.com/track/3KzgdYUlqV6TOG7JCmx2Wg"
         },
        "href": "https://api.spotify.com/v1/tracks/3KzgdYUlqV6TOG7JCmx2Wg",
        "id": "3KzgdYUlqV6TOG7JCmx2Wg",
        "is_local": false,
        "name": "Beyond the Sea",
        "popularity": 65,
        "preview_url": "https://p.scdn.co/mp3-preview/265a0fffe03b363973ddf23f0c8f4e55a3d0b45a?cid=5613d8d50c8e4432ba98aa6605df2d73",
        "track_number": 2,
        "type": "track",
        "uri": "spotify:track:3KzgdYUlqV6TOG7JCmx2Wg"
      },
}

• Service will verify that the tracks.items[0].name.downcase === params.q.downcase. Failing this the service will iterate through tracks.items[0] until the correct Song is found.

Service will then cache the following data to be used when creating the new Song record (after gathering Audio Analysis endpoint response):

• tracks.items[0].external_urls.spotify = The Song's url

• tracks.items[0].name.downcase = The Song's title

• tracks.items[0].id = The Song's spotifyId, will be used to later retrieve audio analysis

As a user, when I am on the dance floor
I should see an indicator for the spot I am supposed to click, at the time I am supposed to click it
So that I click the right spot

As and end user, when on the dance floor
I should see buttons/footprints only on the correct beat and in the right place
So that I can practice accurately.

As an end user, when I am on the dance floor screen,
I should be able to click a button to start a countdown
In order to prepare myself before I start the game

• Dance floor background
• Some kind of fancy thing on taps

As a developer,
When I reference my Spotify API Access Token,
In order to make a request to a Spotify API Endpoint,
I receive a valid Access Token that was generated within the last hour
Spotify API Authentication Docs

• Service should request a new token Every Hour because each token lasts for 1 hour

"Client Credentials" Access Token Request:
Route
POST https://accounts.spotify.com/api/token

Body
x-www-form-urlencoded
{ grant_type: client_credentials }

Headers
Authorization: Basic <client_id:client_secret (*converted to Base64*)>

Response

{
    "access_token": "<access_token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": ""
}

• Refactor database migration to be handled in separate directory from root/main.go

• Include a rollback option and write migrations so they are only triggered from CLI

• Structure table migrations to include a dropTable function that resets the table