Content for  TR 26.857  Word version:  18.0.0

The proposal follows existing practices in 3GPP for device and network APIs, as introduced in clause 4.2, and extends the documentation with best practices identified in other organizations as introduced in clause 4.3.

The basic concept of the Media Service Enabler is to support third-party media delivery over the 5G System. Figure 5.3.2-1 and Figure 5.3.2-2 provide an overview for an application that is deployed on top of a 5G System. In this case, the Application Provider is operating an external DN and connects to the 5G System using N6 for data delivery and possibly N33 to use specific 5G network services. A UE-resident application makes use of device functions (for example hardware and software exposed through APIs) and connects to the Application Provider.

Figure 5.3.2-3 now extends the above basic architecture to provide to the Application Provider a set of 3GPP-specified functions, possibly both on UE and network side, in order to simplify operations. These functions are bundled as a Media Service Enabler (MSE) and offered to the Application Provider as follows:

• The service may be provisioned on the network side using an MSE Application Function. The provisioning reference point is summarized as MSE-1.
• User plane data may be exchanged with the Application Provider using an Ingest/Egest interface, MSE-2. Generally, this is a generic IP-based interface that directly uses N6 and the UPF. However, the MSE may offer specific Application Server functions at MSE-2.
• On the UE side, the functions of an MSE Client are accessed through a well-defined client API, MSE-6, that is aligned with other device APIs. The MSE Client may make use of other device functions that are expected to be accessible via existing device APIs.
• The MSE Client may be decomposed into Core Functions defined in the relevant Media Service Enabler specification, and External Device Reference Functions that are accessed through well-defined APIs MSE-7.
• The MSE Client connects to the 5G network and may make use of Application Functions associated with this Media Service Enabler. Those functions are exposed through MSE-5.
• User data is exchanged with the MSE Application Server (if any) through MSE-4, which may define specific requirements on the usage of protocols, codecs, formats etc.

Providing a Media Service Enabler in this form has several benefits:

• The Application Provider has a set of functions that can be easily accessed in the same way that device functions are accessed today, namely through well-defined device APIs. The Application Provider can also use regular IP connectivity to operate its application.
• For the MSE developer, the focus is on providing a well-defined set of functions that are exposed to the application through MSE-1 and MSE-2 on the network side, and via MSE-6 on the UE device side.
• The MSE developer may provide the MSE Application Function and Application Server as well as the MSE Client. In this case, the primary interoperability aspects are at reference points MSE-1 and MSE-6.
  In another case, the network functions for MSE may be provided by a 5G System operator. In this case the MSE Client and MSE AF are expected to also implement the functions and interoperability defined at reference points MSE-4 and MSE-5.

The following functions are defined:

• Application: A downloadable or installed application in a UE that makes use of the MSE to provide a Media Service to a user.
• MSE Client: A UE-internal function dedicated to a specific Media Service Enabler. The MSE Client is a logical function and its subfunctions may be distributed within the UE according to implementation choice. For example, it may define new core functions as well as referencing existing functions that are required to complete the expected functions.
• MSE Application Function: An Application Function similar to that defined in clause 6.2.10 of TS 23.501, dedicated to a specific Media Service Enabler.
• MSE Application Server: An Application Server dedicated to a specific Media Service Enabler.

The following reference points, interfaces and APIs are defined:

• MSE-1 (MSE Provisioning API): External API, exposed by the MSE AF, which enables the Application Provider to provision the usage of the MSE.
• MSE-2: (MSE Ingest/Egest API): Optional external API exposed to the Application Provider by the MSE AS and used when the MSE AS in the trusted DN is selected to process content for the MSE.
• MSE-4: (MSE User Plane interface): Interface used by an MSE Client to exchange user data with an MSE AS.
• MSE-5: (MSE Control API): APIs exposed by an MSE AF to the MSE Client to configure and control MSE functions.
• MSE-6: (MSE Client APIs): APIs exposed by the MSE to the Application for client-internal communication to make use of MSE functions
• MSE-7: (External Device API): APIs exposed by the UE device to the MSE to make use of resident client functions such as rendering, playback, etc.
• MSE-8: (Application APIs): Interface used for information exchange between the Application and the Application Provider.

Media Service Enabler specifications do not attempt to define an entire service, but only a subset of small defined functions. Hence, it is essential to understand that whatever is not defined to complete a service does not need to be documented. An MSE specification is a bottom-up specification: it specifies what is needed and does not address what is not needed. An MSE specification is proposed to include the following information:

1. Pre-requisites and Assumptions (Highly recommended): Pre-requisites document what is expected to be available either from the 5G System (i.e. certain functionalities of the 5G System) or from implementation (for example functions available on the device). These pre-requisites may be considered to be part of the specification (as reference to an external specification), but it is important to identify this separately in order to clearly demarcate the boundaries of the MSE with respect to other functions. Example for pre-requisites include, but are not limited to:
   1. Existing and required device functions and the corresponding APIs defined as MSE-7.
   2. Existing and required 5G System functions.
2. Overall specification of the function, including a specific architecture (Highly recommended). This includes:
   1. Instantiations of the MSE reference points and functions.
   2. A typical call flow.
3. Specification of the MSE Client functions and the corresponding MSE-6 APIs (Highly recommended). This typically includes functionalities such as configuration, settings, notifications, events, data and status query as well as functional methods. It includes:
   1. Definition of the internal functions itself.
   2. Definition of how to use existing and required device functions.
   3. Strict definition of the API methods with details such as name, pseudo code, functions. As a common language IDL or C is proposed to be used.
4. Control Plane API and network/MSE Application Function (Highly recommended)
   1. Definition of the internal functions of the AF, using common practices of a RESTful API
   2. Alignment with 5G Media Streaming functionalities as defined at reference point M5 of TS 26.501 and TS 26.511, using OpenAPI/YAML.
5. User plane reference point and network/MSE Application Server (Optional but recommended)
   1. Definition of internal functions of the Application Server, based on common Internet protocols, preferably by reference to external specifications (IETF, MPEG, etc.)

Beyond the specification, it is proposed to document guidelines and additional support material for developers. The following aspects are considered:

1. Guidelines for application developers (Highly Recommended)
   • Providing guidance on how an application developer can make use of the Media Service Enabler.
   • This is preferably done by providing examples and implementation hints.
2. Guidelines for MSE implementers (Optional):
   • Providing guidance to an implementer of an MSE Client and/or AF in order to support implementation. Such guidelines may also be provided in line with the specification text.
   • If provided, the guidelines are preferably separated in style and form from the main specification text. For example, this may be added in a specific "box" or "frame" that identifies this as an informal implementation hint.
3. Considerations on device API implementations (Recommended)
   • The device APIs MSE-6 and MSE-7 are typically only documented on a conceptual level.
   • Considerations on the specifics for implementing the APIs, for example in Android as RESTful APIs in devices, is relevant.
4. Considerations of a Conformance Test Suite (Optional, but expected to be at least considered):
   • A Conformance Test Suite is a collection of tests covering the breadth of the MSE functions. The tests include the definition of test cases, the definition of test assets as well as the success criteria to pass the tests. A typical figure for a test application to test the implementation of the MSE Client is shown in Figure 5.3.5-1.
   • The considerations documented are expected to allow third parties to implement a full Conformance Test Suite in order to test the 3GPP-defined APIs and conformance for correct implementation. Follow-up such as adopter programs may be considered.
   • The Conformance Test Suites and adopter program may be provided by external organizations, for example 3GPP market representation partners (MRPs).

The primary goal is to achieve consistency across the API, as well as across all specifications. Consistency makes it easier for developers, editors, reviewers, and users of the documentation to understand and modify it. While each organization and specification may and should have its own look and feel, it is considered appropriate to establish a style guide convention. The Style Guide of the OpenXR Documentation has been branched from the Vulkan documentation and is hence considered a broadly adopted and established convention. In addition, 3GPP uses OpenAPI for the API definition towards the network. Hence, it is proposed to align with the style guide and documentation conventions from OpenXR as well as OpenAPI as follows:

1. Develop APIs for the relevant reference points in a Github- or gitlab-based environment and only port agreements or full specifications to 3GPP specifications. The development of the formal APIs is done in a git-based environment.
2. For device-internal API definitions, align with the OpenXR style guide https://registry.khronos.org/OpenXR/specs/1.0/styleguide.html as follows:
   • Use Asciidoc http://www.asciidoctor.org/ to the extent possible to define formal APIs.
   • For API naming conventions, it is proposed that the rules defined in https://registry.khronos.org/OpenXR/specs/1.0/styleguide.html#naming apply with the following adaptation:
   • Each MSE is assigned a prefix (for example MSE). In similar way as XR is used in the OpenXR spec, an equivalent usage of MSE is expected for an MSE spec. This prefix is used as XR is used in the description above.
   • Prefixes are used in the API to denote specific semantic meaning of MSE names, or as a label to avoid name clashes, and are explained here:
     • MSE/Mse/mse
     • All types, commands, enumerates and C macro definitions in the specification are prefixed with these characters, according to the rules defined above.
   • For the markup style, it is proposed that the ETSI/3GPP documentation rules as well as the rules defined in https://registry.khronos.org/OpenXR/specs/1.0/styleguide.html#markup apply. In particular, section 5.7 on writing reference pages is expected to apply: https://registry.khronos.org/OpenXR/specs/1.0/styleguide.html#writing-refpages
   • Provide reference pages for the MSE according to the OpenXR principle https://registry.khronos.org/OpenXR/specs/1.0/man/html/openxr.html
3. For the network-based APIs and reference points, define RESTful APIs and use the conventional OpenAPI rules as defined by 3GPP in TS 29.501.
4. For regular data communication reference to existing protocols and formats.