Proposed MPEOS API change for HN Content Transformation - Rev 2

» Back to forum topics
  2 posts   Feedicon  
Replies: 1 - Last Post: April 15, 2013 21:35
by: smallman
showing 1 - 2 of 2
Posted: January 15, 2013 05:03 by cpratt

The pending Content Transformation ECs expose to a sufficiently-priveledged application the ability to enumerate platform transformational capabilities, selectively enable transformations per ContentItem, and support streaming of the transformed version of the content represented by the ContentItem.

The HN MPEOS APIs have long included support that enables a platform to express the transformations that a particular piece of content supports (expressed as a DLNA profile ID) when streamed over the home network and allow streaming of alternate profiles. However, the current APIs do not support the general enumeration of transform capabilities without regard to a particular ContentItem, as is required by the draft version of the content transformation ECs. So this support needs to be added to the MPEOS HN API.

Also included in the draft content transformation ECs is the ability to transform content info so-called "adaptive" or "segmented" formats. So support for extracting the platform's segmentation capabilities and content treatment also needs to be added to the MPEOS HN API.

RI MPEOS Support

Here is a more detailed description of the proposed MPEOS changes:

  • Transformation capability enumeration: mpeos_hnServerGetContentTransformationCnt()/ mpeos_hnServerGetContentTransformations()
    • These are used to build the Transformation objects returned via TransformationManager.getSupportedTransformations().
    • DTCP support is implied by RI (all platforms are required to support it). And if there's a call to determine DECE support, it would be handled similarly to DTCP. Short answer: the stack will handle filling in the ProtectionType field.
    • The stack will handle the grouping of OutputVideoTransformations according to their input profile, which simplifies the API.
    • Note the requirement that the segments implied by the segmented content profiles are required to be cross-compatible between HLS and Smooth Streaming. This is due to the fact that the URIs referring to these segments will be incorporated into non-DASH manifests.
  • Transformed profile enumeration: mpeos_hnServerGetDLNAProfileIDStr() parameter *requiresTransform
    • The capability to enumerate the available profiles for a given piece of content have always been there. But we now divide the available transforms into those that are "native" and don't require transformation and those that can only be enabled via TransformationManager
    • e.g. a platform's native format can support MPEG_TS_NA_ISO, MPEG_TS_SD_NA_ISO, MPEG_TS_SD_NA and would have requiresTransform set to FALSE.
    • e.g. a platform might support transforming its native content format to AVC_TS_NA_ISO and DASH_AVC_TS_SD_ISO and would set requiresTransform to TRUE. Note that AVC_TS_NA_ISO is required per OCAP HNP I08. Also note that only DASH_AVC_TS_SD_ISO is a segmented profile and only that profile is applicable to the remaining APIs.
  • Transformation identification for playback: mpe_HnPlaybackParamsMediaServerHttp.transformation
    • When playing back a piece of content using a transformation, the transformation parameter, along with the pre-existing mpe_HnStreamContentLocation, identifies which transformation of a piece of content should be applied when streaming.
    • This enables the stack to honor a content request for a transformed representation of a piece of content.
  • Segmentation parameter enumeration: mpeos_hnServerGetSegmentationInfo()
    • For content profiles that imply segmentation, this allows the segment length, count, and availability time to be determined on a per-item basis.
    • This enables the stack to build manifests for the segmented content profiles
  • Segment identification for playback: mpe_HnPlaybackParamsMediaServerHttp.segmentNumber
    • When playing back a segmented content profile, the segmentNumber, along with the pre-existing mpe_HnStreamContentLocation and the transformation parameter, identifies which segment of which piece of content to stream.
    • This enables the stack to honor a content request for a segment with the segmented content profiles

Changes to mpeos_hn.h: (vs trunk revision 40235)

Transformation capability enumeration:

 * This structure allows the platform to describe its transformational capabilities for
 * HN-streamable content.
 * A element of this structure defines the capability to perform an on-demand transformation
 * of any content natively stored in a format compatible with the designated sourceProfile
 * to the given transformedProfile with the provided restrictions. All audio streams present
 * in the source content must be present in the transformed representation in audio format(s)
 * required/appropriate for the profile.
 * Note that for the following (segmented) profiles, additional requirements apply.
 * Content in these formats must be supplied in segments, with each segment representing
 * the same duration of time, except for the last segment. Each segment must represent a
 * whole number of seconds from 2 to 30 seconds. (Note: The number of segments for a given
 * profile is determined using mpeos_hnServerGetSegmentInfo()).
 * Also, transformed segment representations conforming to profile DASH_AVC_TS_ISO
 * must also be compliant with HLS media file/segment requirements.
 * And transformed segment representations conforming to profile DASH_AVC_MP4
 * must also be compliant with IIS SmoothStreaming AVC/H.264 fragment requirements.
typedef struct _mpe_hnContentTransformation
    int32_t id;                         ///< The numerical ID for the transformation
    char sourceProfile[MPE_HN_MAX_DLNA_PROFILE_ID_STR_SIZE];
                                        ///< The source DLNA profile that can be converted
    char transformedProfile[MPE_HN_MAX_DLNA_PROFILE_ID_STR_SIZE];
                                        ///< The transformed DLNA profile
    int32_t bitrate;                    ///< The maximum (fixed) bitrate for this transformation (in kbps)
    int32_t width;                      ///< The maximum horizontal resolution for this transformation
    int32_t height;                     ///< The maximum vertical resolution for this transformation
    mpe_Bool progressive;               ///< The supported frame format (progressive/interlaced)
} mpe_hnContentTransformation;


 * Retrieves number/count of support content transformation from the platform.
 * See the definition of mpe_hnContentTransformation for more information.
 * @param contentTransformationCnt  Returns number/count of supported transformations. If 0,
 *                                  the platform doesn't provide any transformations.
 * @return MPE_HN_ERR_NOERR            If successful.
mpe_Error mpeos_hnServerGetContentTransformationCnt(uint32_t * contentTransformationCnt);


 * Retrieves the supported content transformations from the platform. See the definition of
 * mpe_hnContentTransformation for more information.
 * @param contentTransformations  Address of an array sufficient to hold the number of
 * content transformations structures returned from mpeos_hnServerGetContentTransformationCnt.
 * Note: Each mpe_hnContentTransformation must have a unique ID.
 * @return MPE_HN_ERR_NOERR            If successful.
mpe_Error mpeos_hnServerGetContentTransformations(
        mpe_hnContentTransformation contentTransformations[]);

Transformed profile enumeration:

Note: Parameters requiresTransform added to the existing mpe_HnPlaybackParamsMediaServerHttp() function.

 * Returns DLNA profile ID string at requested index from array of possible
 * DLNA profile IDs which are applicable to supplied content item. This method
 * will return profileIDStr, assuming caller has allocated memory whose size is
 * The index number also indicates the platform preferred DLNA profile ID. For
 * example, index 0 is the most preferred playback format for streaming of this
 * content item, index 1 is the second most preferred format, etc.
 * The underlying HN server implementation should never include "DTCP_"
 * prefixed profiles.
 * @param contentLocation       Indicates content location type such as
 *                              recording, TSB, etc.
 * @param contentDescription    Structure describing content which varies
 *                              depending on content location type provided.
 * @param idx                   Retrieve this index in array of supported DLNA
 *                              profile IDs (indices start at 0, through
 *                              count-1), based on count returned via
 *                              mpeos_hnServerGetDLNAProfileIDsSizeCnt().
 * @param profileIDStr          Returns requested DLNA profiles ID string from
 *                              specified index in caller allocated memory of
 *                              MPE_HN_MAX_DLNA_PROFILE_ID_STR_SIZE.
 * @param requiresTransform     Returns an indication that support for the given
 *                              profile will require the use of transformation
 *                              resources when streamed. This should be false
 *                              when the profile identified by profileIDStr
 *                              is compatible with the native format. e.g.
 *                              when profileIDStr is returned as "MPEG_TS_NA_ISO"
 *                              (or "MPEG_TS_SD_NA_ISO"/"MPEG_TS_HD_NA_ISO") and the
 *                              platform natively stores content as MPEG2
 *                              TransportStreams, requiresTransform should be
 *                              false.
 * @return MPE_HN_ERR_NOERR            If successful.
 * @return MPE_HN_ERR_INVALID_PARAM    If content type is not supported or
 *                                     index is out of range.
mpe_Error mpeos_hnServerGetDLNAProfileIDStr(
        mpe_HnStreamContentLocation contentLocation, void * contentDescription,
        uint32_t idx, char profileIDStr[MPE_HN_MAX_DLNA_PROFILE_ID_STR_SIZE],
        mpe_Bool *requiresTransform );

Segmentation parameter enumeration:
 * This structure allows the platform to describe the segmented characteristics for a piece
 * of content that can be represented in a segmented format.
typedef struct _mpe_hnSegmentedContentInfo
    uint16_t segmentDurationSec;      ///< The duration of each content segment, in whole segments
    uint32_t numberOfSegments;        ///< The number of segments required to stream the content
    uint64_t availabilityTimeMs;      ///< The availability time of the first segment (in
                                      ///< milliseconds since the Unix epoch, Jan 1 1970, 00:00:00
                                      ///< UTC). Each successive segment will be presumed to have
                                      ///< an availability time equal to this value plus the sum of
                                      ///< all segment durations preceding the segment
} mpe_hnSegmentedContentInfo;


 * Returns the segment info for the designated piece of content.
 * Note that this method is only applicable for particular profiles and only
 * for content that supports the given profile as supplied via
 * mpeos_hnServerGetDLNAProfileIDStr() on the particular content.
 * e.g. content exposed in the following profiles must support this method:
 * Note that segment representations conforming to profile DASH_AVC_TS_ISO and
 * must also be compliant with HLS media file/segment requirements.
 * Segment representations conforming to profile DASH_AVC_MP4
 * must also be compliant with IIS SmoothStreaming AVC/H.264 fragment requirements.
 * @param contentLocation       Indicates content location type such as
 *                              recording, TSB, etc.
 * @param contentDescription    Structure describing content which varies
 *                              depending on content location type provided.
 * @param profileIDStr          The target profile for the designated content.
 * @param segmentInfo           Pointer to the segmentation info structure that will
 *                              return the segment information for the designated
 *                              content.
 * @return MPE_HN_ERR_NOERR            If successful.
 * @return MPE_HN_ERR_INVALID_PARAM    If content location is invalid or
 *                                     the profile is not supported.
mpe_Error mpeos_hnServerGetSegmentationInfo(
        mpe_HnStreamContentLocation contentLocation, void * contentDescription,
        char profileIDStr[MPE_HN_MAX_DLNA_PROFILE_ID_STR_SIZE],
        mpe_hnSegmentedContentInfo *segmentInfo );

Segment identification for playback:

Note: Fields transformation and segmentNumber are added to the existing mpe_HnPlaybackParamsMediaServerHttp structure.

typedef struct _mpe_HnPlaybackParamsMediaServerHttp
    mpe_HnStreamContentLocation contentLocation;    ///< Supplies the type of the content description that follows.

    void * contentDescription;                      ///< A reference to a recording, a TSB, personal content
                                                    ///< item, or a tuner.

    float playspeedRate;                            ///< Requested playspeed rate. Normal (1x) or trick-play (!=1x).
                                                    ///<  For segmented content, this field is ignored.

    int64_t startBytePosition;                      ///< Start streaming data from this byte position. If -1, use
                                                    ///< default start media time appropriate for dlnaProfileId
                                                    ///< associated with the underlying streaming session. In
                                                    ///< particular, this value will be -1 for
                                                    ///< MPE_HN_CONTENT_LOCATION_LOCAL_VIDEO_DEVICE.

    int64_t endBytePosition;                        ///< End streaming when this byte position is reached. If -1,
                                                    ///< stream until no more content is available in the direction
                                                    ///< of playspeedRate.

    uint32_t cciDescSize;                           ///< Number of CCI descriptor insertions that need to be performed.

    mpe_HnPlaybackTransportCCI* cciDescData;        ///< Pointer to an allocated structure that conveys per-PID copy
                                                    ///< control information for DTCP descriptor embedding in the
                                                    ///< outgoing stream. Allocated memory equals
                                                    ///< cciDescSize * sizeof(mpe_HnPlaybackTransportCCI).
    mpe_hnContentTransformation * transformation;   ///< Pointer to an allocated structure that conveys the requested
                                                    ///< transformed version of the resource. If the native version
                                                    ///< of the content is being streamed, this will be NULL.

    uint16_t segmentNumber;                         ///< For segmented content, the segment number to stream.
                                                    ///<  When provided, playspeedRate is ignored.

Any/all feedback is appreciated.
Posted: April 15, 2013 21:35 by smallman
The review period for the proposed MPEOS changes has ended.
Replies: 1 - Last Post: April 15, 2013 21:35
by: smallman