Retrieve file for playback

The audio/video file could be delieved to end-user web browser using three different ways:

1) Your web appliation requests the signed file URL using MiaRec REST API, then it re-sends that URL to end-user web browser. The web-browser retrieves the file directly from MiaRec web portal using the signed file URL.

2) Your web application retrieves file using MiaRec REST API and resends the file back to end-user web browser.

3) Your web application retrieves call metadata using MiaRec REST API, then gets access to MiaRec file storage directly and streams the file to end-user web browser.

Method #1 (recommended)

Your web appliation requests the signed file URL using MiaRec REST API. The generated URL is returned to end-user web browser. The web-browser uses the signed URL to request the file directly from MiaRec web portal.

How it works

Step 1. The end-user web browser connects to your web application and requests a playback of particular call. For example, you could render the following HTML web page to end-user:
```
<audio controls>
    <source src="https://YOUR-WEB-SERVER/recordings/CALL-ID" type="audio/mpeg">
</audio>
```
* Step 2. Your web appliation sends the "Generate File URL" request to MiaRec web server using REST API:
```
/api/v2/calls/{call-id}.json/file_url.json?expires=3600
```
The expires query parameter specifies for how long the URL should be valid (in seconds). The end-user will not be able to access the URL after expiration.

Optionally, you can pass file_id query parameter to retrieve the particular file instance of the call:
```
/api/v2/calls/{call-id}.json/file_url.json?expires=3600&file_id=01
```

The call may have multiple files in cases when automatic silence detection is enabled. In these cases, the recording is split on multiple files at silence periods. By default, silence detection is disabled. If the file_id is missing, then MiaRec web portal automatically concatenates multiple files into one on flight.

Step 3. MiaRec web portal returns JSON-formatted response containing the secure signed URL, like:
```
{
   "signed_url": "https://miarec.example.com/calls/file/e03f497d-bdff-11e7-2790-4b6ab9967d89/signed?expires=1493100525&sign=NMxBcIFB6t2M...<TRUNCATED>"
}
```
The URL is signed by MiaRec web server using encryption methods. MiaRec validates the signature when it receives such URL back from the end-user (see step 5). If signature is invalid, then the URL is rejected. The signature protects the important URL parameters from modification (call-id, expires, host name, etc.). I.e. this URL is valid only for particular call and only for a limited permiod of time (see expires parameter above). * Step 4. Your web application needs to return URL to the end-user web browser, for example, inside HTTP Location header, like:
```
HTTP/1.1 302 Found
Location: https://miarec.example.com/calls/file/e03f...<TRUNCATED>
```
Caution!

You may generate the signed URL in advance when generating HTML web page (not recommended), like:
```
<audio>
    <source src="https://miarec.example.com/calls/file/e03f...<TRUNCATED>" type="audio/mpeg">
</audio>
```
We do not recommend to do that because it creates unecessary load on MiaRec web server. In this example, URL has to be generated for each HTML page display even if the user doesn't playback the call. If you display 50 call recordings on page (in table, for example), then you need to request 50 Signed URLs in advance from MiaRec web server. It is time consuming because you need to send 50 HTTP requests to MiaRec.

Better solution is to route file requests to your own web application first and then redirect to MiaRec web server when necessary, like:
```
<audio controls>
    <source src="https://YOUR-WEB-SERVER/recording/CALL-ID" type="audio/mpeg">
</audio>
```
This URL should point to your web application. If end-user clicks "play" button in media player, then his/her web-browser automatically opens that URL. On your web application side you receive such request, parse "call-id", validate user's permissions and then ask MiaRec web portal to generate the signed URL for that particular call (see step 2). * Step 5. When web-browser receives HTTP 302 Found response with Location header, it automatically tries to open the returned URL (for user it is transparent). * Step 6. The MiaRec web portal verifies the signature and expiration parameters. If everyting is ok, then it connects to database and reads the file location from there. * Step 7. MiaRec web portal reads the file from the file storage. * Step 8. The file content is streamed directly to the end-user web browser.

Things to consider

It is a responsibility of your web application to check user permissions. You should verify user's role/group and credentials before you return the signed URL to user. MiaRec web portal gracefully generate signed URLs for any call that is accessible by your REST API account. Although, on MiaRec side you could limit access rights for your REST API account, i.e. you could grant your web application permissions only to particular recordings identified by tenant/group/user.
If both MiaRec web-portal and your web application are located in the same private network, then you could use HTTP (non-encrypted) protocol for REST API connection for optimization purposes. But for end-user to MiaRec web-portal communication, you need to use HTTPS (encrypted) protocol, i.e. you should deploy appropriate SSL certificate on MiaRec web server.

Method #2

Your web application retrieves file using MiaRec REST API. The your web application resends the file to end-user web browser.

How it works

Step 1. The end-user web browser connects to your web application and requests playback of particular call.
Step 2. Your web appliation sends the "Get file" request to MiaRec web server using REST API:
```
/api/v2/calls/{call-id}.json/file
```
Optionally, you can pass file_id query parameter to retrieve a particular file instance within the call:
```
/api/v2/calls/{call-id}.json/file?file_id=01
```
* Step 3. MiaRec web portal reads the file location from own database. * Step 4. MiaRec web portal reads the file from the file storage * Step 5. MiaRec web portal streams the file to your web application in a response to the request in step 2. Normally, at this moment, your web application should store temporary the file locally before it can pass that file further to end-user. * Step 6. Your web application streams the file to the web browser in a response to the request in step 1.

Things to consider:

The network connection between end-user and your web application may be significantly slower than the connection between your web app and MiaRec server(s). This means that the file streaming operation (step 6) may time out eventually, especially on big files. Your web application should support resumable file download using HTTP Range headers.
If your web application and MiaRec web portal are located in different datacenters, then such solution incurs additional bandwidth usage. For each file, your web application has to download it first from MiaRec web portal (inbound traffic), then re-transfer it to the end-user (outbound traffic).

Method #3

Your web application retrieves call metadata using MiaRec REST API. The call metadata contains the file path. This file path is used to access the file directly on MiaRec file storage and stream it to end-user web browser.

How it works

Step 1. The end-user web browser connects to your web application and requests playback of particular call.
Step 2. Your web appliation sends the "Get Call Metadata" request to MiaRec web server using REST API:
```
/api/v2/calls/{call-id}.json
```
* Step 3. MiaRec web portal reads call metadata from own database. * Step 4. Your web application receives JSON-formatted response from MiaRec containing call metadata like:
```
{
"call": {
 "call_id":          "e03f497d-bdff-1019-102d-68be3896f081",
 "from_number":      "102",
 "to_number":        "101",
 ...
 "files": [{
    "file_id": "01",
    "start_time": "2013-10-12T16:32:22-0800",
    "stop_time": "2013-10-12T16:38:56-0800",
    "file_size": 132000,
    "file_path": "/var/recordings/20131012/20131012163222-534346ad00000003.mp3",
 }]
}
```
The call metadata conteins the file location. In the example above, the file_path attribute is /var/recordings/20131012/20131012163222-534346ad00000003.mp3. * Step 5. Your web application needs to access the file directly on MiaRec storage.

Note, the file_path in JSON response points to the file location accessible from the MiaRec servers. In order to access these files from your own server, you could use NFS file sharing, i.e. mount the local directory /var/recordings to remote NFS share. Instructions of how to configure NFS is out of scope of this document. Alternatively, you could use SSHFS instead of NFS. * Step 6. Your web application streams the file to the web browser in a response to the request in step 1.

Things to consider:

You need to have physical access and appropriate permissions to the MiaRec file storage in order to enable NFS file sharing there.
The NFS traffic is not encrypted. This means, that you could use NFS only within your private network only. You probably, could use VPN connection between your web app and MiaRec file storage, but this complicates the overall architecture. If a secure file transmission is required between your web application and MiaRec file server, then you should consider other methods described in this document.
This solution doesn't works with encrypted files. MiaRec may optionally encrypt the files on storage. When you access file storage directly from your web application, then the resulting audio/video files are not playable (they are kept in encrypted format). Other methods do support on-flight decryption (see below).

Advantages:

Resumable download is easier to achieve comparing to the previous method, because you can use your web server capabilities to serve files directly. It is a responsibility of the web-server to handle HTTP Range header, i.e. you do not need to worry about processing Range header.

Compatibility with file encryption

Methods 1 and 2 do support file encryption. The file is automatically decrypted on flight by MiaRec web portal during file streaming. The REST API account credentials are used to decrypt the file. This means that your REST API account has to be granted access to the appropriate file encryption key.

In method 3 (when your web application does access file storage directly), the read file remains encrypted (obviously). If you use this method, then you need to disable file encryption in MiaRec.