API: Media - QutEcoacoustics/baw-server GitHub Wiki

Media API Spec

Request

Parameters are query strings
Missing query strings revert to defaults
Some defaults are invariant, some are based on audio recording properties
- AudioEventId: null by default (New functionality)
- Channel is by default, invariant, and mix-down (0)
- Sample rate is by default, audio_recording.sample_rate
- bit rate is by default audio_recording.bit_rate_bps ( provide this information as metadata - don’t allow it to be changed for now)
- window - 512 (==> 256px) by default
window function (Hamming by default)
mimetype/ ext
- NO DEFAULT
- None specified == route error
- Priorities listed in available formats
colour: greyscale by default
ppms (provide this information as metadata - don’t allow it to be changed)
- option deprecated
- currently returns (erroneously) ideal ppms
- return calculated/native ppms as metadata
Defaults do not need to be included in query string

Response

if no query string provided, responds with all params set to defaults, plus possible options. If any query string, responds with settings provided and defaults, without possible options
new json structure:
- original
  - properties of audio that don’t change
    - original sample rate, duration, id, uuid, recording start datetime, etc
- current
  - properties of the current resource view (may not be necessary, will always be json). maybe merge original & current into root objec?
  - start, end, sample rate, channel, etc
- available
  - These represent metadata for resources that can’t return meta data
  - Results objects for each available format should hold all the parameters that would generate the same resource (including the url - only the specified parameters)
    - so fields should include all options (default or otherwise)
    - plus: extension, mime_type, and url
  - defaults represented by order
    - e.g. mp3, flac, wav (so mp3 is default)
  - resource views that are available
    - audio
      - all supported audio formats
    - image
      - e.g. spectrogram/png, waveform/png (for now, only png spectrogram)
    - meta data
      - e.g. json/xml/csv (for now only support JSON)
- Options
  - these are different between audio and image
  - return IFF no query string provided
    - e.g. staging.ecosounds.org/audio_recordings/234234/media.json
  - max, min duration
    - different for image/audio formats
  - windows sizes available
  - colours available
  - sample rates available
  - bit rate options
  - media type options
  - channel options
  - window functions available

GET staging.ecosounds.org/audio_recordings/234234/media.json?start_offset=0.0&end_offset=30.0

Original format

{
"datetime":"2012-10-20T06:00:00+10:00",
"original_format":".wav",
"original_sample_rate":22050,
"start_offset":0.0,
"end_offset":30.0,
"uuid":"7de42123-c14e-4c10-afdf-8badd894864f",
"id":234234,
"media_type":"application/json",
"available_audio_formats":{
"mp3":{
"extension":"mp3",
"channel":0,
"sample_rate":22050,
"max_duration_seconds":300.0,
"min_duration_seconds":0.5,
"mime_type":"audio/mp3",
"url":"/audio_recordings/234234/media.mp3?end_offset=30.0\u0026start_offset=0.0"
},
"webm":{
"extension":"webm",
"channel":0,
"sample_rate":22050,
"max_duration_seconds":300.0,
"min_duration_seconds":0.5,
"mime_type":"audio/webm",
"url":"/audio_recordings/234234/media.webm?end_offset=30.0\u0026start_offset=0.0"
},
"ogg":{
"extension":"ogg",
"channel":0,
"sample_rate":22050,
"max_duration_seconds":300.0,
"min_duration_seconds":0.5,
"mime_type":"audio/ogg",
"url":"/audio_recordings/234234/media.ogg?end_offset=30.0\u0026start_offset=0.0"
},
"flac":{
"extension":"flac",
"channel":0,
"sample_rate":22050,
"max_duration_seconds":300.0,
"min_duration_seconds":0.5,
"mime_type":"audio/x-flac",
"url":"/audio_recordings/234234/media.flac?end_offset=30.0\u0026start_offset=0.0"
},
"wav":{
"extension":"wav",
"channel":0,
"sample_rate":22050,
"max_duration_seconds":300.0,
"min_duration_seconds":0.5,
"mime_type":"audio/wav",
"url":"/audio_recordings/234234/media.wav?end_offset=30.0\u0026start_offset=0.0"
}
},
"available_image_formats":{
"png":{
"extension":"png",
"channel":0,
"sample_rate":22050,
"window":512,
"window_function":"Hamming",
"colour":"g",
"ppms":0.045,
"max_duration_seconds":120.0,
"min_duration_seconds":0.5,
"mime_type":"image/png",
"url":"/audio_recordings/234234/media.png?end_offset=30.0\u0026start_offset=0.0"
}
},
"available_text_formats":{
"json":{
"extension":"json",
"mime_type":"application/json",
"url":"/audio_recordings/234234/media.json?end_offset=30.0\u0026start_offset=0.0"
}
},
"format":"json"
}

Example new format output

{
  "recording": {
    "id": 266,
    "uuid": "b5235035-5714-4b79-9be1-1094c9b6db2d",
    "recorded_date": "2012-03-26T07:06:59+10:00",
    "duration_seconds": 60000,
    "sample_rate_hertz": 22050,
    "channel_count": 2,
    "media_type": "audio/mp3"
  },
  "common_parameters": {
    "start_offset": 1,
    "end_offset": 2,
    "audio_event_id": null,
    "channel": 0,
    "sample_rate": 22050
  },
  "available": {
    "audio": {
      "mp3": {
        "media_type": "audio/mp3",
        "extension": "mp3",
        "url": "/audio_recordings/266/media.mp3?end_offset=2&start_offset=1"
      },
      "webm": {
        "media_type": "audio/webm",
        "extension": "webm",
        "url": "/audio_recordings/266/media.webm?end_offset=2&start_offset=1"
      },
      "ogg": {
        "media_type": "audio/ogg",
        "extension": "ogg",
        "url": "/audio_recordings/266/media.ogg?end_offset=2&start_offset=1"
      },
      "flac": {
        "media_type": "audio/x-flac",
        "extension": "flac",
        "url": "/audio_recordings/266/media.flac?end_offset=2&start_offset=1"
      },
      "wav": {
        "media_type": "audio/wav",
        "extension": "wav",
        "url": "/audio_recordings/266/media.wav?end_offset=2&start_offset=1"
      }
    },
    "image": {
      "png": {
        "window_size": 512,
        "window_function": "Hamming",
        "colour": "g",
        "ppms": 0.04306640625
        "media_type": "image/png",
        "extension": "png",
        "url": "/audio_recordings/266/media.png?end_offset=2&start_offset=1"
      }
    },
    "text": {
      "json": {
        "media_type": "application/json",
        "extension": "json",
        "url": "/audio_recordings/266/media.json?end_offset=2&start_offset=1"
      }
    }
  },
  "options": {
    "valid_sample_rates": [
      8000,
      11025,
      12000,
      16000,
      22050,
      24000,
      32000,
      44100,
      48000
    ],
    "channels": [
      0,
      1,
      2
    ],
    "audio": {
      "duration_max": 300,
      "duration_min": 0.5,
      "formats": [
        "mp3",
        "webm",
        "ogg",
        "flac",
        "wav"
      ]
    },
    "image": {
      "spectrogram": {
        "duration_max": 120,
        "duration_min": 0.5,
        "formats": [
          "png"
        ],
        "window_sizes": [
          128,
          256,
          512,
          1024,
          2048,
          4096
        ],
        "window_functions": [
          "Hann",
          "Hamming",
          "Bartlett",
          "Rectangular",
          "Kaiser"
        ],
        "colours": {
          "g": "greyscale"
        }
      }
    },
    "text": {
      "formats": [
        "json"
      ]
    }
  }
}
```