Example

POST /playbacks/1283791327846/control?operation=next

Existing Operations

The existing operations will work as follows:

• restart - restarts the current media in the list.
• pause - pauses the current media in the list.
• unpause - unpauses the current media in the list.
• reverse - reverses the current media in the list. If that causes the media to reach the beginning of a sound file, it will do one of the two following actions:
  1. If the previous media resource was a sound file, it will start playback of the previous media resource at an offset equal to the remaining jump not displaced in the existing sound file.
  2. If the previous media resource was not a sound file (and cannot be indexed), it will start playback at the start of that resource.
• forward - fast-forwards the current media in the list. if that causes the media to reach the end of a sound file, the sound file will complete and the next media resource will be started.
  1. If the next media resource is a sound file, it will start playback of the next media resource at an offset equal to the remaining jump not displaced in the existing sound file.
  2. If the next media resource was not a sound file (and cannot be indexed), it will start playback at the start of that resource.

Configuration

No configuration should be needed.

Design/Implementation

Swagger Model updates

The channels and bridges resources will have their respective play operations updated to allow multiple media query parameters. The list is constructed in the order that the query parameters are presented.

                         {
                            "name": "media",
                            "description": "Media URIs to play.",
                            "paramType": "query",
                            "required": true,
                            "allowMultiple": true,
                            "dataType": "string"
                        },

The playbacks resource will have its control operation updated with new options for the operation query parameter.

                         {
                            "name": "operation",
                            "description": "Operation to perform on the playback.",
                            "paramType": "query",
                            "required": true,
                            "allowMultiple": false,
                            "dataType": "string",
                            "allowableValues": {
                                "valueType": "LIST",
                                "values": [
                                    "restart",
                                    "pause",
                                    "unpause",
                                    "reverse",
                                    "forward",
                                    "next",
                                    "prev"
                                ]
                            }
                        }

Core updates

• New control frames for next and prev should be added:

    AST_CONTROL_STREAM_STOP = 1000,        /*!< Indicate to a channel in playback to stop the stream */
    AST_CONTROL_STREAM_SUSPEND = 1001,    /*!< Indicate to a channel in playback to suspend the stream */
    AST_CONTROL_STREAM_RESTART = 1002,    /*!< Indicate to a channel in playback to restart the stream */
    AST_CONTROL_STREAM_REVERSE = 1003,    /*!< Indicate to a channel in playback to rewind */
    AST_CONTROL_STREAM_FORWARD = 1004,    /*!< Indicate to a channel in playback to fast forward */
    AST_CONTROL_STREAM_PREV = 1005,       /*!< Indicate to a channel in playback to play the previous stream */
    AST_CONTROL_STREAM_NEXT = 1006,       /*!< Indicate to a channel in playback to play the next stream */

• Update channel.c to consume and ignore the two new frame types
• Have file.c waitstream_core handle the two new frame types. These should break out of the control loop and return the frame value.
  Update file.c ast_waitstream_fr_cb to accept an arbitrary void *. Update waitstream_core and its variants that pass a callback to also pass a void *. Modify waitstream_control to pass the void * to the callback.
• Add a new function to app.h (because we don't have enough yet) called ast_control_streamfile_lang_w_cb. Its usage should be somewhat obvious.

res_stasis_playback

In addition model and parameter changes that will ripple through the auto-generated HTTP server/resource bindings, the control of the playback will have to be modified in the following ways in res_stasis_playback:

• The stasis_app_playback struct will have to specify a list of media resources to play, as well as the current/next file to be played.
• play_on_channel will have to iterate over that list. If ast_control_streamfile_lang returns a next or prev result, it will have to handle it accordingly.
  • Use ast_control_streamfile_lang_w_cb instead of ast_control_streamfile_lang. Pass the stasis_app_playback object as the void *. If the rewind or fast forward operation indicates that we are at the beginning or end of a file, alter the next file to be played accordingly.
  • Implement handling for the control frame values corresponding to PREV and NEXT.
• Add two new function handlers for playback_opreation_cb - playback_next and playback_prev. Queue the control frames appropriately.

app_controlplayback

Currently, the ControlPlayback dialplan application does not support playback of multiple files. As such, handling of the new feature should be defensive in nature only.

• controlplayback_exec should be modified to handle the return of AST_CONTROL_STREAM_PREV and AST_CONTROL_STREAM_NEXT gracefully. Since the application does not currently handle multiple playbacks, it should simply return with the correct CPLAYBACKSTATUS as PREVIOUS or NEXT, respectively.
• controlplayback_manager should be updated to understand "prev" and "next" as valid control signals (as, who knows, you may want to use AMI to control a channel in ARI, if you're that crazy)

res_agi

The control stream file AGI command does not support playback of multiple files. As such, handling of the new feature should be defensive in nature only.

• handle_controlstreamfile should be modified to handle the return of AST_CONTROL_STREAM_PREV and AST_CONTROL_STREAM_NEXT gracefully. The result of CPLAYBACKSTATUS should mirror that of app_controlplayback.

chan_iax2

• Explicitly specify that the two new control frames should not be passed over the wire.

func_frame_trace

• Do the frame trace dance

Testing

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 - Write Tests That Fail

In both of these cases, it is expected that the existing tests can be used as a basis.

Phase Two - Update the core/non-ARI portions

Phase Three - Update ARI