2.2.6. Media feeds and sessions

2.2.6.1. About feeds

The Proximie SDK has a number of different ways to share and process audio and video media. This section provides an overview of the media feed and session classes available in the SDK.

Both audio and video are handled using “feed” objects. When feeds are used to send or receive media with another participating service or application, they are associated with a “session”.

There are three of categories of feed:

  • Media server feeds, which are used to send and receive media to and from the Proximie media services. For more information on media server feeds, see the Media Server Session section.

  • Peer feeds, which are used to communicate directly between two peers on the same network. For more information on peer feed, see the Peer Streaming section.

  • Utility feeds, which are used to process or modify audio and video locally. For more information on utility feeds, see the Utility Feeds section.

2.2.6.2. Feed classes

All feeds have a common base class PxMedia::FeedBase, which has a standard set of operations to get details about the feed, and to start and stop the feed streaming (referred to as “playing” by the SDK).

Feeds are always created as shared pointers (i.e. std::shared_ptr) using a factory method or builder helper for the concrete feed class being instantiated.

Feeds can have additional interfaces for specialised functionality, which are obtained using an accessor function on the feed - e.g. an application would call mediaServerFeed() on a MediaServerFeed feed object to get the unique media server feed interface.

We use this approach rather than inheritance as certain interfaces (now or in future) may be shared between feeds with different inheritance hierarchies - for example, an audio interface may appear on any type of feed, media session, peer or utility.

For more information on using these different feed types see the following sections:

Feed lifetimes

As mentioned above, feed objects are always created using the create factory method. Initially the application has the only reference to the feed, and releasing that reference will free the object.

For feeds that belong to a session (media server session or peer session), the session also takes ownership of any feed that has been started (namely using startFeed()). When the feed is stopped (e.g. using stopFeed()) any owning session will release its reference to the feed. Consequently, feed objects that are playing in a session will continue to live even if the application disposes of its shared pointer reference. Only when both the application and the session have released their references to the feed will the feed object be destroyed.

When a session is closed, all feeds that belong to the session are stopped and released from the session. If the application has a feed reference at this point, it remains alive but is no longer associated with the session and will report itself as stopped.

Feed life cycles

All feeds follow a life cycle of creation, starting, stopping and destruction. The life cycle has callbacks that your application can use to track the state of each feed and respond to events such as errors or changes in the feed state.

The feed life cycle is as follows:

  1. Creation

    • All feeds are created into shared pointers by a class factory function (typically called create) or builder helper object.

    • Depending on the feed type, creation takes various “components” (such as input source or output target) as parameters which are used to build the feed. See the later sections in this guide for the various options available to make up feeds.

    • Newly created feeds are initially inactive and ready to be started. Before starting, the creator can set up any feed callbacks such as onFeedStarted() or onFeedStopped() to track the feed state and respond to events.

  2. Start playing

    • The feed owner calls the feed’s startFeed() method to start the feed. startFeed() begins the process of starting the feed.

    • If the feed is not in a state to be started (e.g. already playing), the startFeed() function immediately returns an error result.

    • Otherwise, it returns a successful result and the feed is in the process of starting, asynchronously.

  3. Feed playing

    • After successfully calling startFeed(), the feed will subsequently start playing, and it calls the callback set by onFeedStarted().

    • However, if the feed failed during the starting process, it will call the callback set by onFeedStopped(), with an error code indicating the failure reason.

  4. Stop playing

    • When a feed is playing, the owner can call the feed’s stopFeed() function to stop the feed.

    • Again, this process is asynchronous; the feed will call the callback set by onFeedStopped() when the feed has stopped.

    • In the event that the feed encounters an error while playing, it will stop and also call the onFeedStopped() callback, with an error code indicating the failure reason.

Note that once a feed has stopped (directly or due to an error), it cannot be restarted.