Video

Video is particularly difficult, as it typically requires multiple files (one video, one audio) to be useful. Container formats are beyond the scope of this project. To support video, remote playback of URIs should support a parallel form of extraction using the pipe | character:

same => n,Playback(http://myserver.com/monkeys.h264|http://myserver.com/monkeys.wav)

The behaviour of the files retrieved in such a fashion are as follows:

• Playback does not begin until all files are retrieved.
• Files are treated individually in the cache.
• While files with different names can be played back, the first file in the parallel list will be the actual "core sound file" played back. That is, assuming monkeys.h264 and monkeys.wav already existed on the server, the Playback operation would operate on sound file monkeys, which would play both the audio and video files.

Persistence

The cached entries and their metadata should be stored in the AstDB. When Asterisk starts, the entries in the AstDB should be verified to still be accurate (that is, that the local files still exist), and if so, the buckets for them re-created.

Playback of a URI

Playback of a URI can be done via any of the supported playback operations, through any API. This functionality should be a part of the Asterisk core, and available through any of the media playback operations.

Dialplan

same => n,Playback(http://myserver.com/monkeys.wav)

Note that this can be combined with multiple URIs or sounds to form a playlist:

same => n,Playback(http://myserver.com/monkeys.wav&http://myserver.com/weasels.wav)

Since an & is valid for a URI but is also used as a separator in dialplan, ampersands in a resource cannot be supported. If an ampersand is used in a URI (say, as part of a query), then the entire URI must be URI encoded.

AGI

CONTROL STREAM FILE http://myserver.com/monkeys.wav "" 3000

ARI

Playback can be done on either a channel or a bridge. Since the resource being requested is a URI, it should be presented in the body of the request encoded using text/uri-list (see RFC 2483). Note that we still need to provide a media query parameter that specifies the resource type to play - the actual 'entity' being played back is simply specified in the body of the request.

http://localhost:8088/ari/channels/12345/play/p1?media=uri:list

Content-Type: text/uri-list
http://myserver.com/monkeys.wav

This format works nicely with simple playlists, as it can specify multiple files to retrieve. Note that these files should be played back sequentially as a playlist (which is not yet supported, but will need to be by the time we get here!)

http://localhost:8088/ari/channels/12345/play/p2?media=uri:list

Content-Type: text/uri-list
# Audio File One (I'm a comment and should be ignored)
http://myserver.com/monkeys.wav
# Comment comment comment
http://myserver.com/awesome-sound.wave

Note that when the Content-Type is text/uri-list, the resource specified by the uri media scheme is simply tossed away, as we can only have a single list of URIs. Note that this approach is somewhat limiting in that supporting multiples

Another option is to provide the URIs in JSON. This would allow parallel playback of files for video support. Note that the JSON must follow the following schema:

http://localhost:8088/ari/channels/12345/play/p3

{
    "media": "playlist",
    "playlist": [
                  { "media_group": [
                              {
                                "scheme": "uri",
                                "resource": "http://myserver.com/monkeys.wav"
                              },
                              {
                                "scheme": "uri",
                                "resource": "http://myserver.com/monkeys.h264"
                              }
                            ]
                          }
                 { "media_group": [
                              { "scheme": "uri",
                                "resource": "http://myserver.com/awesome-sound.wav",
                              }
                            ]
                          }
                ]
}
    

There's some obvious differences here:

1. The schema type must be playlist. We can't use a uri schema type, as doing so would prevent combining URI resources with other media resource types for playlists.
2. The playlist must be strongly typed. Otherwise, swagger code generation turns into a nightmare. As such, that means a new strongly named body parameter must be used.

Configuration

No configuration should be needed.

Design

Core - media_cache

This new file in the Asterisk core will provide the following:

• A universal API that the core and rest of Asterisk can do to query for something in the media cache.
• Caching of the bucket information in the AstDB
• Informing the bucket implementation that a new bucket has been created during startup (or otherwise creating the buckets itself)
• CLI commands

Implementations of a cache should implement the bucket API for a particular scheme.

API

CLI Commands

core show media-cache

Just for fun! It'd be good to see what is in the cache, the timestamps, etc.

*CLI>core show media-cache

URI                                  Last update                Local file
http://myserver.com/awesome.wav      2014-10-30 00:52:25 UTC    /var/spool/asterisk/media_cache/ahsd98d1.wav
http://myserver.com/monkeys.wav      2014-09-14 10:10:00 UTC    /var/spool/asterisk/media_cache/77asdf7a.wav
http://myserver.com/monkeys.h264     2014-09-14 10:10:00 UTC    /var/spool/asterisk/media_cache/77asdf7a.h264 

3 items found.

Note that the last two files would have been created using a preferred file prefix. This allow the file and app core to "find" both the audio and the video file when opening up the stream returned by the file_path by the media_cache.

core clear media-cache

This is really a handy way for a system administrator to force files to be pulled down.

*CLI>core clear media-cache

3 items purged.

*CLI>core show media-cache

URI                                  Last update                Local file
0 items found.

res_http_media_cache

File Retrieval

A module should be implemented that does the actual work of using libcurl to retrieve a media file from the system subject to caching constraints, if they exist. It should:

• Implement the HTTP caching, noted previously
• cURL files down to a local file, create a bucket, and store the bucket along with the appropriate metadata

Core - Usage of ast_openstream

Prior to call ast_openstream, users who want to support URI playback should first:

• Determine if the provided "file" is actually a URI. A simple 'strncmp' is sufficient for this.
• If so, ask the cache for the actual file. Use that for subsequent calls to ast_openstream and ast_openvstream.
• If not, move on as normal.

Core - file.c::ast_streamfile

This covers most functionality, as most dialplan applications (and other things) end up calling ast_streamfile.

AGI - res_agi.c::handle_streamfile | handle_getoption

AGI implementations of basic sound playback, which emulate their dialplan counterparts. These will need to be updated in the same way as ast_streamfile.

Core - HTTP server

Support for a new Content-Type, text/uri-list, needs to be added to the HTTP server. Since we typically parse the body as JSON using ast_http_get_json, this should be a new public function ast_http_get_uri_list that pulls a body as a text/uri-list. Since we now have core support for URIs, a bit of basic support for a list of URIs should be added to uri.h and used by the HTTP server.

http.h

uri.h

ARI

Swagger Schema

Providing a 'type' for the media parameter is a bit tricky. We have the following situation:

• If the media parameter does not specify a resource type of uri, treat it as a string.
• If the media parameter does specify a resource type of uri, look to the body as a URI list.
• If the media parameter is in the body, however, it must be of type string. Hence, we cannot specify the URIs directly in the media parameter. Thus, to specify URIs, a body parameter of playlist must be provided and the URIs provided in a Playlist model object.

Note that the following for channels.json would be repeated for bridges.json:

Mustache Templates

The Mustache templates generated will need to be modified to check for text/uri-list as a possible body type:

• The existing body_parsing.mustache should be renamed to note that it parses JSON. The caller of the body_parsing routines should be made to only look at the results if the function returns non-NULL.
  • If it does return NULL, it should also check for a text/uri-list using the new function in http.h.
  • The body parsers should be updated for a playback operation to return the structured Playback object.

• A new text_uri_body_parser should be added that parses a body into a struct ast_uri_list. This should be hard-typed to convert the URI list into a structured Playback object.

  Icon

  This is limiting, but for now, we don't have any use for a URI list in ARI outside of specifying a list of media resources. If that assumption proves false later, that code should be re-visited.

Test Plan

Unit Tests

Asterisk Test Suite

Project Planning

The following are rough tasks that need to be done in order to complete this feature. These are meant to be guidelines, and should not necessarily be followed verbatim. Note that many of these are actually independent of each other, and can be worked out simultaneously. If you're interested in helping out with any of these tasks, please speak up on the asterisk-dev mailing list!

The various phases are meant to be implemented as separately as possible to ease the process of peer review.

Phase One - Core Media Cache

See peer reviews:

• https://gerrit.asterisk.org/#/c/487/
• https://gerrit.asterisk.org/#/c/488/

Phase Two - res_http_media_cache

Phase Three - Core/dialplan/AGI implementations

Phase Four - ARI Playlists

Phase Five - HTTP Server Updates

Phase Six - ARI text/uri-list support/URI playbacks

JIRA Issues

ASTERISK-25654 - Playback: Add the ability to play remote URIs Closed

Contributors

Reference Information

http%3A%2F%2Fmyserver.com%2Fmedia%3Fsound%3Dmonkeys%26format%3Dwav