File

/x-epi/files/{fileid}

GET

Returns the details of a particular audio resource

URI Parameters fileId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

HTTP Status Code: 200

Returned when the audio resource exists

Body: application/json

{
    "channels": integer - the number of audio channels,
    "created": string - iso date and time the resource was created,
    "modified": string - iso date and time the label/description of the resource was last modified,
    "file_modified": string - iso date and time showing when the file was last modified,
    "description": string -  user entered description,
    "format": 
    {
        "subtype": string - the number of bits/sample and whether the sample is an int/float etc,
        "type": string - the type of audio file (wav, mp3, flac etc)
    },
    "label": string - a human readable title,
    "length": integer - length of the audio file in milliseconds,
    "locked": boolean - true if the file is locked because it is playing or queued to play,
    "path": string - the path to where the file lives on the Pi,
    "samplerate": integer - the sample rate of the audio file in Hz,
    "type": string - the resource type (either sndfile or mp3),
    "uid": string - the unique id of the resource,
    "valid": boolean - true if the file associated with the resource is valid audio
}

HTTP Status Code: 404

Returned when the audio resource does not exist

Body: application/json

{
    "code": 404,
    "error": "Not Found"
}

PATCH

Updates the meta-data (label and description) associated with the audio file

Body: application/json

{
    "label": string - optional the new label for the audio resource,
    "description": string - optional new description for the audio resource
}

HTTP Status Code: 423

Returned when the system has been locked using the Status API endpoint

Body: application/json

{
    "result": false,
    "reason": 
    [
        "the system is locked"
    ]
}

PUT

Replaces the audio file for this resource and optionally the meta data

Body: multipart/form-data

• label - string - a human readable title of the audio resource (optional)
• description - string - a user entered description of the audio resource (optional)
• file - file - the file containing the audio (required)

HTTP Status Code: 200

The audio resource has been uploaded successfully

Body: application/json

{
    "result": boolean - true if this particular audio resource was uploaded,
    "uid": string - the unique id of the resource if it was uploaded,
    "details": 
    {
        "channels": integer - the number of audio channels,
        "created": string - iso date and time the resource was created,
        "description": string -  user entered description,
        "format": 
        {
            "subtype": string - the number of bits/sample and whether the sample is an int/float etc,
            "type": string - the type of audio file (wav, mp3, flac etc)
        },
        "label": string - a human readable title,
        "length": integer - length of the audio file in milliseconds,
        "locked": boolean - true if the file is locked because it is playing or queued to play,
        "path": string - the path to where the file lives on the Pi,
        "samplerate": integer - the sample rate of the audio file in Hz,
        "type": string - the resource type (either sndfile or mp3),
        "uid": string - the unique id of the resource,
        "valid": boolean - true if the file associated with the resource is valid audio
    }             
}

HTTP Status Code: 400

The data sent to the endpoint was incorrect ins some way

Body: application/json

{
    "result": boolean - false, 
    "reason": [ an array of strings giving the reasons for the failure ]
}

HTTP Status Code: 423

Returned when the system has been locked using the Status API endpoint or is locked through playing

Body: application/json

{
    "result": false,
    "reason": 
    [
        string - a reason for failure,
    ]
}

DELETE

Deletes the resource

URI Parameters fileId: required(string - pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$)

HTTP Status Code: 200

Returned if the resource is deleted

Body: application/json

{
    "result": true
}

HTTP Status Code: 404

Returned when the resource cannot be found

Body: application/json

{
    "result": false,
    "reason": 
    [
        string - reason for failure
    ]
}

HTTP Status Code: 423

Returned when

• the system has been locked using the Status API endpoint
• the resource has been locked as it is playing
• the resource has been locked as it is part of a playlist or schedule

Body: application/json

{
    "result": false,
    "reason": 
    [
        string - reason for failure,
    ],
    "details": (optional) shows the schedules and/or playlists the file is referenced by.
    {
        "playlists":
        [
            {
                "label": string - label of playlist,
                "uid": string - the unique identifier of the playlist
            },...
        ],
        "schedules":
                [
            {
                "label": string - label of schedule,
                "uid": string - the unique identifier of the schedule
            },...
        ]
    }
}