1.3.12. Feed Requests

Overview

So far SDK feeds have been chiefly static in behaviour after creation. To allow feeds to behave dynamically, the SDK provides a mechanism to send “feed requests” to a given feed, which it resolves depending on the feed type and the components used to create it.

Whilst the roster of request types is limited today, the SDK will continue to add new request types in future releases.

Feed request handling

There are two ways that a feed request can be supported in any given feed:

  1. The feed type itself supports a request - e.g. certain types of need can support adaptive streaming requests*.

  2. A feed component used within a feed confers the ability to handle one or more request types - e.g. if the VideoStagePrivacy component is added to a feed, that feed can handle requests to change the privacy of the video stream.

* Adaptive streaming today is not actually implemented using the feed request mechanism, but will be in the future.

Walkthrough

To demonstrate an example of using feed requests, the following example will use VideoStagePrivacy. This component is a “stage” as described in the Feed Stages section.

Assuming some video input (in this case VideoInputFeedV4Linux2), we add a video stage of type VideoStagePrivacy:

using namespace Proximie;
using namespace PxMedia;

VideoInputFeedV4Linux2 video;
video.videoCapabilities().frameRate(30);  // etc...

VideoStagePrivacy privacy;
video.videoStages().sequence({privacy});

Then, the feed is created as usual:

VideoOutputFeedAuto output;  // Some output...

UtilityVideoLocalFeed::FeedProperties props{"video"};
auto created = UtilityVideoLocalFeed::create(context, props, video, output);
if (!created) {
    auto error = created.error();
    // Handle the error...
}
auto feed = created.value().get();

After the feed is created, your application can call its feedRequest() method to make a request. Requests are objects that contain the required parameters; in this case a simple boolean flag to indicate whether privacy should be enabled or not.

// A request object to set the privacy on (true)
VideoStagePrivacy::RequestPrivacy privacyOn(true);

// Send the request to the feed
auto handled = feed->feedRequest(privacyOn);
if (!handled) {
    auto error = handled.error();
    // Handle the error...
}

A feed request returns an outcome which indicates if the request was successfully handled or not. The application may examine the outcome’s error code (if any) to determine the reason for failure.

Common reasons for failure include:

  • The feed is not able to accept the request - e.g. it is not playing, or has been stopped.

  • The request is not recognised by the feed - e.g. making a privacy request on a feed that did not have a VideoStagePrivacy stage.

  • Some other error related to the request itself, such as invalid parameters.

Available feed requests

Requests are typically specific to a the type of feed or the components used within it (e.g. RequestPrivacy is a nested class belonging to VideoStagePrivacy).

All feed request types are derived from FeedRequest. For more details and a list of available feed request subclasses, see the API documentation for FeedRequest itself.