From 9ce2caebb32e312057facc5a265d2af9ca4fb474 Mon Sep 17 00:00:00 2001
From: Bo-Rong Chen <borongchen@google.com>
Date: Tue, 16 Apr 2024 12:37:37 -0700
Subject: [PATCH] Update starboard media header description

This PR updates the description in drm.h, decode_target.h, media.h, and player.h.

b/326450058
---
 starboard/decode_target.h |  46 +++---
 starboard/drm.h           |  73 +++++----
 starboard/media.h         | 165 +++++++++----------
 starboard/player.h        | 325 ++++++++++++++++++++------------------
 4 files changed, 320 insertions(+), 289 deletions(-)

diff --git a/starboard/decode_target.h b/starboard/decode_target.h
index 6034a5a1f5e5..ba4560f48d50 100644
--- a/starboard/decode_target.h
+++ b/starboard/decode_target.h
@@ -24,7 +24,7 @@
 // copies, and also avoiding pushing data between CPU and GPU memory
 // unnecessarily.
 //
-// # SbDecodeTargetFormat
+// * SbDecodeTargetFormat
 //
 // SbDecodeTargets support several different formats that can be used to decode
 // into and render from. Some formats may be easier to decode into, and others
@@ -33,7 +33,7 @@
 // an error. Each decoder provides a way to check if a given
 // SbDecodeTargetFormat is supported by that decoder.
 //
-// # SbDecodeTargetGraphicsContextProvider
+// * SbDecodeTargetGraphicsContextProvider
 //
 // Some components may need to acquire SbDecodeTargets compatible with a certain
 // rendering context, which may need to be created on a particular thread. The
@@ -42,7 +42,7 @@
 // rendering context that will be used to render the SbDecodeTarget objects.
 // For GLES renderers, it also provides functionality to enable the Starboard
 // implementation to run arbitrary code on the application's renderer thread
-// with the renderer's EGLContext held current.  This may be useful if your
+// with the renderer's EGLContext held current. This may be useful if your
 // SbDecodeTarget creation code needs to execute GLES commands like, for
 // example, glGenTextures().
 //
@@ -104,10 +104,10 @@ typedef enum SbDecodeTargetFormat {
 #endif  // SB_API_VERSION >= 14
 
   // A decoder target format consisting of a single plane with pixels laid out
-  // in the format UYVY.  Since there are two Y values per sample, but only one
+  // in the format UYVY. Since there are two Y values per sample, but only one
   // U value and only one V value, horizontally the Y resolution is twice the
-  // size of both the U and V resolutions.  Vertically, they Y, U and V all
-  // have the same resolution.  This is a YUV 422 format.  When using this
+  // size of both the U and V resolutions. Vertically, they Y, U and V all
+  // have the same resolution. This is a YUV 422 format. When using this
   // format with GL platforms, it is expected that the underlying texture will
   // be set to the GL_RGBA format, and the width of the texture will be equal to
   // the number of UYVY tuples per row (e.g. the u/v width resolution).
@@ -157,19 +157,19 @@ typedef void (*SbDecodeTargetGlesContextRunner)(
 
 // In general, the SbDecodeTargetGraphicsContextProvider structure provides
 // information about the graphics context that will be used to render
-// SbDecodeTargets.  Some Starboard implementations may need to have references
+// SbDecodeTargets. Some Starboard implementations may need to have references
 // to some graphics objects when creating/destroying resources used by
-// SbDecodeTarget.  References to SbDecodeTargetGraphicsContextProvider objects
+// SbDecodeTarget. References to SbDecodeTargetGraphicsContextProvider objects
 // should be provided to all Starboard functions that might create
 // SbDecodeTargets.
 typedef struct SbDecodeTargetGraphicsContextProvider {
   // A reference to the EGLDisplay object that hosts the EGLContext that will
-  // be used to render any produced SbDecodeTargets.  Note that it has the
-  // type |void*| in order to avoid #including the EGL header files here.
+  // be used to render any produced SbDecodeTargets. Note that it has the
+  // type |void*| in order to avoid including the EGL header files here.
   void* egl_display;
   // The EGLContext object that will be used to render any produced
-  // SbDecodeTargets.  Note that it has the
-  // type |void*| in order to avoid #including the EGL header files here.
+  // SbDecodeTargets. Note that it has the
+  // type |void*| in order to avoid including the EGL header files here.
   void* egl_context;
 
   // The |gles_context_runner| function pointer is passed in from the
@@ -220,9 +220,9 @@ typedef struct SbDecodeTargetInfoPlane {
   int height;
 
   // The following properties specify a rectangle indicating a region within
-  // the texture/surface that contains valid image data.  The top-left corner
-  // is (0, 0) and increases to the right and to the bottom.  The units
-  // specified by these parameters are number of pixels.  The range for
+  // the texture/surface that contains valid image data. The top-left corner
+  // is (0, 0) and increases to the right and to the bottom. The units
+  // specified by these parameters are number of pixels. The range for
   // left/right is [0, width], and for top/bottom it is [0, height].
   SbDecodeTargetInfoContentRegion content_region;
 } SbDecodeTargetInfoPlane;
@@ -234,13 +234,13 @@ typedef struct SbDecodeTargetInfo {
   // expected in |planes|.
   SbDecodeTargetFormat format;
 
-  // Specifies whether the decode target is opaque.  The underlying
+  // Specifies whether the decode target is opaque. The underlying
   // source of this value is expected to be properly maintained by the Starboard
-  // implementation.  So, for example, if an opaque only image type were decoded
+  // implementation. So, for example, if an opaque only image type were decoded
   // into an SbDecodeTarget, then the implementation would configure things in
-  // such a way that this value is set to true.  By opaque, it is meant
+  // such a way that this value is set to true. By opaque, it is meant
   // that all alpha values are guaranteed to be 255, if the decode target is of
-  // a format that has alpha values.  If the decode target is of a format that
+  // a format that has alpha values. If the decode target is of a format that
   // does not have alpha values, then this value should be set to true.
   // Applications may rely on this value in order to implement certain
   // optimizations such as occlusion culling.
@@ -252,7 +252,7 @@ typedef struct SbDecodeTargetInfo {
   int height;
 
   // The image planes (e.g. kSbDecodeTargetPlaneRGBA, or {kSbDecodeTargetPlaneY,
-  //  kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV} associated with this
+  // kSbDecodeTargetPlaneU, kSbDecodeTargetPlaneV}) associated with this
   // decode target.
   SbDecodeTargetInfoPlane planes[3];
 } SbDecodeTargetInfo;
@@ -299,8 +299,8 @@ static inline int SbDecodeTargetNumberOfPlanesForFormat(
 // Returns ownership of |decode_target| to the Starboard implementation.
 // This function will likely result in the destruction of the SbDecodeTarget and
 // all its associated surfaces, though in some cases, platforms may simply
-// adjust a reference count.  This function must be called on a thread with
-// the context
+// adjust a reference count. This function must be called on a thread with
+// the context.
 SB_EXPORT void SbDecodeTargetRelease(SbDecodeTarget decode_target);
 
 // Writes all information about |decode_target| into |out_info|.
@@ -312,7 +312,7 @@ SB_EXPORT bool SbDecodeTargetGetInfo(SbDecodeTarget decode_target,
 
 // Inline convenience function to run an arbitrary
 // SbDecodeTargetGlesContextRunnerTarget function through a
-// SbDecodeTargetGraphicsContextProvider.  This is intended to be called by
+// SbDecodeTargetGraphicsContextProvider. This is intended to be called by
 // Starboard implementations, if it is necessary.
 static inline void SbDecodeTargetRunInGlesContext(
     SbDecodeTargetGraphicsContextProvider* provider,
diff --git a/starboard/drm.h b/starboard/drm.h
index 1fcebb06f0c9..ca3acefdd75d 100644
--- a/starboard/drm.h
+++ b/starboard/drm.h
@@ -48,13 +48,13 @@ typedef enum SbDrmStatus {
   kSbDrmStatusNotSupportedError,
   kSbDrmStatusInvalidStateError,
   kSbDrmStatusQuotaExceededError,
-  // The following error can be used when the error status cannot be mapped to
-  // one of the above errors.
+  // The kSbDrmStatusUnknownError can be used when the error status cannot be
+  // mapped to one of the rest errors.
   kSbDrmStatusUnknownError,
 } SbDrmStatus;
 
 // Status of a particular media key.
-// https://w3c.github.io/encrypted-media/#idl-def-MediaKeyStatus
+// https://www.w3.org/TR/encrypted-media/#idl-def-mediakeystatus
 typedef enum SbDrmKeyStatus {
   kSbDrmKeyStatusUsable,
   kSbDrmKeyStatusExpired,
@@ -134,7 +134,7 @@ typedef struct SbDrmSystemPrivate* SbDrmSystem;
 // |type| is the status of the session request.
 //
 // |error_message| may contain an optional error message when |status| isn't
-// |kSbDrmStatusSuccess| to provide more details about the error.  It may be
+// |kSbDrmStatusSuccess| to provide more details about the error. It may be
 // NULL if |status| is |kSbDrmStatusSuccess| or if no error message can be
 // provided.
 // |ticket| will be the same ticket that was passed to
@@ -142,7 +142,7 @@ typedef struct SbDrmSystemPrivate* SbDrmSystem;
 // request was generated by the DRM system.
 //
 // |session_id| cannot be NULL when |ticket| is |kSbDrmTicketInvalid|, even when
-// there was an error generating the request.  This allows Cobalt to find and
+// there was an error generating the request. This allows Cobalt to find and
 // reject the correct Promise corresponding to the associated
 // SbDrmGenerateSessionUpdateRequest().
 typedef void (*SbDrmSessionUpdateRequestFunc)(SbDrmSystem drm_system,
@@ -167,7 +167,7 @@ typedef void (*SbDrmSessionUpdateRequestFunc)(SbDrmSystem drm_system,
 // |status| is the status of the session request.
 //
 // |error_message| may contain an optional error message when |status| isn't
-// |kSbDrmStatusSuccess| to provide more details about the error.  It may be
+// |kSbDrmStatusSuccess| to provide more details about the error. It may be
 // NULL if |status| is |kSbDrmStatusSuccess| or if no error message can be
 // provided.
 // |succeeded| is whether the session was successfully updated or not.
@@ -180,8 +180,14 @@ typedef void (*SbDrmSessionUpdatedFunc)(SbDrmSystem drm_system,
                                         int session_id_size);
 
 // A callback for notifications that the status of one or more keys in a session
-// has been changed.  All keys of the session and their new status will be
-// passed along.  Any keys not in the list is considered as deleted.
+// has been changed. All keys |key_ids| of the session and their new status
+// will be passed along. Any keys not in the list are considered as deleted.
+//
+// |number_of_keys| is the number of keys.
+//
+// |key_ids| is a pointer of a vector contains keys.
+//
+// |key_statuses| is a pointer of a vector contains the status of each key.
 typedef void (*SbDrmSessionKeyStatusesChangedFunc)(
     SbDrmSystem drm_system,
     void* context,
@@ -191,7 +197,7 @@ typedef void (*SbDrmSessionKeyStatusesChangedFunc)(
     const SbDrmKeyId* key_ids,
     const SbDrmKeyStatus* key_statuses);
 
-// A callback for signalling that a session has been closed by the SbDrmSystem
+// A callback for signalling that a session has been closed by the SbDrmSystem.
 typedef void (*SbDrmSessionClosedFunc)(SbDrmSystem drm_system,
                                        void* context,
                                        const void* session_id,
@@ -234,29 +240,33 @@ static SB_C_FORCE_INLINE bool SbDrmTicketIsValid(int ticket) {
 // SbDrmUpdateSession() for more details.
 //
 // |key_system|: The DRM key system to be created. The value should be in the
-// form of "com.example.somesystem" as suggested by
-// https://w3c.github.io/encrypted-media/#key-system. All letters in the value
+// form of "com.example.somesystem". All letters in the value
 // should be lowercase and will be matched exactly with known DRM key systems of
-// the platform.
+// the platform. See https://w3c.github.io/encrypted-media/#key-system
+//
 // |context|: A value passed when any of this function's callback parameters are
 // called.
+//
 // |update_request_callback|: A function that is called every time after
 // SbDrmGenerateSessionUpdateRequest() is called.
+//
 // |session_updated_callback|: A function that is called every time after
 // SbDrmUpdateSession() is called.
+//
 // |key_statuses_changed_callback|: A function that can be called to indicate
 // that key statuses have changed.
+//
 // |server_certificate_updated_callback|: A function that is called to report
-// whether the server certificate has been successfully updated.  It is called
-// once and only once.  It is possible that the callback is called before the
+// whether the server certificate has been successfully updated. It is called
+// once and only once. It is possible that the callback is called before the
 // function returns.
+//
 // |session_closed_callback|: A function that can be called to indicate that a
 // session has closed.
 // If |NULL| is passed for any of the callbacks (|update_request_callback|,
 // |session_updated_callback|, |key_statuses_changed_callback|,
 // |server_certificate_updated_callback|, or |session_closed_callback|), then
 // |kSbDrmSystemInvalid| must be returned.
-
 SB_EXPORT SbDrmSystem SbDrmCreateSystem(
     const char* key_system,
     void* context,
@@ -294,9 +304,11 @@ SB_EXPORT SbDrmSystem SbDrmCreateSystem(
 // used.
 //
 // |type|: The case-sensitive type of the session update request payload. Must
-//   not be NULL.
+// not be NULL.
+//
 // |initialization_data|: The data for which the session update
-//   request payload is created. Must not be NULL.
+// request payload is created. Must not be NULL.
+//
 // |initialization_data_size|: The size of the session update request payload.
 SB_EXPORT void SbDrmGenerateSessionUpdateRequest(
     SbDrmSystem drm_system,
@@ -339,28 +351,31 @@ SB_EXPORT void SbDrmCloseSession(SbDrmSystem drm_system,
                                  int session_id_size);
 
 // Returns true if server certificate of |drm_system| can be updated via
-// SbDrmUpdateServerCertificate().  The return value should remain the same
+// SbDrmUpdateServerCertificate(). The return value should remain the same
 // during the life time of |drm_system|.
 //
 // |drm_system|: The DRM system to check if its server certificate is updatable.
 // Must not be |kSbDrmSystemInvalid|.
 SB_EXPORT bool SbDrmIsServerCertificateUpdatable(SbDrmSystem drm_system);
 
-// Update the server certificate of |drm_system|.  The function can be called
-// multiple times.  It is possible that a call to it happens before the callback
+// Update the server certificate of |drm_system|. The function can be called
+// multiple times. It is possible that a call to it happens before the callback
 // of a previous call is called.
 // Note that this function should only be called after
 // |SbDrmIsServerCertificateUpdatable| is called first and returned true.
 //
 // |drm_system|: The DRM system whose server certificate is being updated. Must
-//   not be |kSbDrmSystemInvalid|.
+// not be |kSbDrmSystemInvalid|.
+//
 // |ticket|: The opaque ID that allows to distinguish callbacks from multiple
-//   concurrent calls to SbDrmUpdateServerCertificate(), which will be passed to
-//   |server_certificate_updated_callback| as-is. It is the responsibility of
-//   the caller to establish ticket uniqueness, issuing multiple requests with
-//   the same ticket may result in undefined behavior. The value
-//   |kSbDrmTicketInvalid| must not be used.
+// concurrent calls to SbDrmUpdateServerCertificate(), which will be passed to
+// |server_certificate_updated_callback| as-is. It is the responsibility of
+// the caller to establish ticket uniqueness, issuing multiple requests with
+// the same ticket may result in undefined behavior. The value
+// |kSbDrmTicketInvalid| must not be used.
+//
 // |certificate|: Pointer to the server certificate data. Must not be NULL.
+//
 // |certificate_size|: Size of the server certificate data.
 SB_EXPORT void SbDrmUpdateServerCertificate(SbDrmSystem drm_system,
                                             int ticket,
@@ -377,7 +392,7 @@ SB_EXPORT void SbDrmUpdateServerCertificate(SbDrmSystem drm_system,
 // using url safe base64 without padding and line wrapping. On systems using
 // Widevine CE CDM with oemcrypto 16 or later, it should return the metrics
 // retrieved via Cdm::getMetrics(), encoded using url safe base64 without
-// padding and line wrapping.  The returned pointer should remain valid and its
+// padding and line wrapping. The returned pointer should remain valid and its
 // content should remain unmodified until the next time this function is called
 // on the associated |drm_system| or the |drm_system| is destroyed.
 //
@@ -396,12 +411,12 @@ SB_EXPORT const void* SbDrmGetMetrics(SbDrmSystem drm_system, int* size);
 // destroyed unless any associated SbPlayer or SbDecoder has first been
 // destroyed.
 //
-// All callbacks are guaranteed to be finished when this function returns.  As a
+// All callbacks are guaranteed to be finished when this function returns. As a
 // result, if this function is called from a callback that is passed to
 // SbDrmCreateSystem(), a deadlock will occur.
 //
 // |drm_system|: The DRM system to be destroyed. Must not be
-//   |kSbDrmSystemInvalid|.
+// |kSbDrmSystemInvalid|.
 SB_EXPORT void SbDrmDestroySystem(SbDrmSystem drm_system);
 
 #ifdef __cplusplus
diff --git a/starboard/media.h b/starboard/media.h
index fca1792933f6..345340c04d62 100644
--- a/starboard/media.h
+++ b/starboard/media.h
@@ -149,7 +149,7 @@ typedef enum SbMediaAudioFrameStorageType {
   // "L0 R0 L1 R1 L2 R2 ...".
   kSbMediaAudioFrameStorageTypeInterleaved,
 
-  // The samples of each channel are stored in their own continuous buffer.  For
+  // The samples of each channel are stored in their own continuous buffer. For
   // example, for a stereo stream with channels L and R that contains samples
   // with timestamps 0, 1, 2, etc., the samples are stored in two buffers
   // "L0 L1 L2 ..." and "R0 R1 R2 ...".
@@ -311,9 +311,7 @@ typedef enum SbMediaRangeId {
 
 // HDR (High Dynamic Range) Metadata common for HDR10 and WebM/VP9-based HDR
 // formats, together with the ColorSpace. HDR reproduces a greater dynamic range
-// of luminosity than is possible with standard digital imaging. See the
-// Consumer Electronics Association press release:
-// https://www.cta.tech/News/Press-Releases/2015/August/CEA-Defines-%E2%80%98HDR-Compatible%E2%80%99-Displays.aspx
+// of luminosity than is possible with standard digital imaging.
 typedef struct SbMediaColorMetadata {
   // Number of decoded bits per channel. A value of 0 indicates that the
   // BitsPerChannel is unspecified.
@@ -405,7 +403,7 @@ typedef struct SbMediaVideoStreamInfo {
   // The video codec of this sample.
   SbMediaVideoCodec codec;
 
-  // The mime of the video stream when |codec| isn't kSbMediaVideoCodecNone.  It
+  // The mime of the video stream when |codec| isn't kSbMediaVideoCodecNone. It
   // may point to an empty string if the mime is not available, and it can only
   // be set to NULL when |codec| is kSbMediaVideoCodecNone.
   const char* mime;
@@ -418,7 +416,7 @@ typedef struct SbMediaVideoStreamInfo {
   // SbMediaCanPlayMimeAndKeySystem(), for example, when it is set to
   // "width=1920; height=1080; framerate=15;", the video will never adapt to
   // resolution higher than 1920x1080 or frame per second higher than 15 fps.
-  // When the maximums are unknown, this will be set to an empty string.  It can
+  // When the maximums are unknown, this will be set to an empty string. It can
   // only be set to NULL when |codec| is kSbMediaVideoCodecNone.
   const char* max_video_capabilities;
 
@@ -462,7 +460,7 @@ typedef struct SbMediaVideoSampleInfo {
   // The video codec of this sample.
   SbMediaVideoCodec codec;
 
-  // The mime of the video stream when |codec| isn't kSbMediaVideoCodecNone.  It
+  // The mime of the video stream when |codec| isn't kSbMediaVideoCodecNone. It
   // may point to an empty string if the mime is not available, and it can only
   // be set to NULL when |codec| is kSbMediaVideoCodecNone.
   const char* mime;
@@ -475,7 +473,7 @@ typedef struct SbMediaVideoSampleInfo {
   // SbMediaCanPlayMimeAndKeySystem(), for example, when it is set to
   // "width=1920; height=1080; framerate=15;", the video will never adapt to
   // resolution higher than 1920x1080 or frame per second higher than 15 fps.
-  // When the maximums are unknown, this will be set to an empty string.  It can
+  // When the maximums are unknown, this will be set to an empty string. It can
   // only be set to NULL when |codec| is kSbMediaVideoCodecNone.
   const char* max_video_capabilities;
 
@@ -544,7 +542,7 @@ typedef struct SbMediaAudioStreamInfo {
   // The audio codec of this sample.
   SbMediaAudioCodec codec;
 
-  // The mime of the audio stream when |codec| isn't kSbMediaAudioCodecNone.  It
+  // The mime of the audio stream when |codec| isn't kSbMediaAudioCodecNone. It
   // may point to an empty string if the mime is not available, and it can only
   // be set to NULL when |codec| is kSbMediaAudioCodecNone.
   const char* mime;
@@ -561,8 +559,7 @@ typedef struct SbMediaAudioStreamInfo {
   // The size, in bytes, of the audio_specific_config.
   uint16_t audio_specific_config_size;
 
-  // The AudioSpecificConfig, as specified in ISO/IEC-14496-3, section 1.6.2.1:
-  // http://read.pudn.com/downloads98/doc/comm/401153/14496/ISO_IEC_14496-3%20Part%203%20Audio/C036083E_SUB1.PDF
+  // The AudioSpecificConfig, as specified in ISO/IEC-14496-3, section 1.6.2.1.
   const void* audio_specific_config;
 } SbMediaAudioStreamInfo;
 
@@ -577,18 +574,18 @@ typedef struct SbMediaAudioSampleInfo {
 
 #else  // SB_API_VERSION >= 15
 
-// An audio sample info, which is a description of a given audio sample.  This
+// An audio sample info, which is a description of a given audio sample. This
 // acts as a set of instructions to the audio decoder.
 //
 // The audio sample info consists of information found in the |WAVEFORMATEX|
 // structure, as well as other information for the audio decoder, including the
-// Audio-specific configuration field.  The |WAVEFORMATEX| structure is
-// specified at http://msdn.microsoft.com/en-us/library/dd390970(v=vs.85).aspx.
+// Audio-specific configuration field. The |WAVEFORMATEX| structure is
+// specified at http://msdn.microsoft.com/en-us/library/dd390970(v=vs.85).aspx .
 typedef struct SbMediaAudioSampleInfo {
   // The audio codec of this sample.
   SbMediaAudioCodec codec;
 
-  // The mime of the audio stream when |codec| isn't kSbMediaAudioCodecNone.  It
+  // The mime of the audio stream when |codec| isn't kSbMediaAudioCodecNone. It
   // may point to an empty string if the mime is not available, and it can only
   // be set to NULL when |codec| is kSbMediaAudioCodecNone.
   const char* mime;
@@ -614,8 +611,7 @@ typedef struct SbMediaAudioSampleInfo {
   // The size, in bytes, of the audio_specific_config.
   uint16_t audio_specific_config_size;
 
-  // The AudioSpecificConfig, as specified in ISO/IEC-14496-3, section 1.6.2.1:
-  // http://read.pudn.com/downloads98/doc/comm/401153/14496/ISO_IEC_14496-3%20Part%203%20Audio/C036083E_SUB1.PDF
+  // The AudioSpecificConfig, as specified in ISO/IEC-14496-3, section 1.6.2.1.
   const void* audio_specific_config;
 } SbMediaAudioSampleInfo, SbMediaAudioStreamInfo;
 
@@ -630,47 +626,47 @@ typedef struct SbMediaAudioSampleInfo {
 // |kSbMediaSupportNotSupported| if either is NULL.
 //
 // |mime|: The mime information of the media in the form of |video/webm| or
-//   |video/mp4; codecs="avc1.42001E"|. It may include arbitrary parameters like
-//   "codecs", "channels", etc.  Note that the "codecs" parameter may contain
-//   more than one codec, delimited by comma.
-// |key_system|: A lowercase value in the form of "com.example.somesystem" as
-//   suggested by https://w3c.github.io/encrypted-media/#key-system that can be
-//   matched exactly with known DRM key systems of the platform.  When
-//   |key_system| is an empty string, the return value is an indication for
-//   non-encrypted media.
+// |video/mp4; codecs="avc1.42001E"|. It may include arbitrary parameters like
+// "codecs", "channels", etc. Note that the "codecs" parameter may contain
+// more than one codec, delimited by comma.
 //
-//   An implementation may choose to support |key_system| with extra attributes,
-//   separated by ';', like
-//   |com.example.somesystem; attribute_name1="value1"; attribute_name2=value1|.
-//   If |key_system| with attributes is not supported by an implementation, it
-//   should treat |key_system| as if it contains only the key system, and reject
-//   any input containing extra attributes, i.e. it can keep using its existing
-//   implementation.
-//   When an implementation supports |key_system| with attributes, it has to
-//   support all attributes defined by the Starboard version the implementation
-//   uses.
-//   An implementation should ignore any unknown attributes, and make a decision
-//   solely based on the key system and the known attributes.  For example, if
-//   an implementation supports "com.widevine.alpha", it should also return
-//   `kSbMediaSupportTypeProbably` when |key_system| is
-//   |com.widevine.alpha; invalid_attribute="invalid_value"|.
-//   Currently the only attribute has to be supported is |encryptionscheme|.  It
-//   reflects the value passed to `encryptionScheme` of
-//   MediaKeySystemMediaCapability, as defined in
-//   https://wicg.github.io/encrypted-media-encryption-scheme/, which can take
-//   value "cenc", "cbcs", or "cbcs-1-9".
-//   Empty string is not a valid value for |encryptionscheme| and the
-//   implementation should return `kSbMediaSupportTypeNotSupported` when
-//   |encryptionscheme| is set to "".
-//   The implementation should return `kSbMediaSupportTypeNotSupported` for
-//   unknown values of known attributes.  For example, if an implementation
-//   supports "encryptionscheme" with value "cenc", "cbcs", or "cbcs-1-9", then
-//   it should return `kSbMediaSupportTypeProbably` when |key_system| is
-//   |com.widevine.alpha; encryptionscheme="cenc"|, and return
-//   `kSbMediaSupportTypeNotSupported` when |key_system| is
-//   |com.widevine.alpha; encryptionscheme="invalid"|.
-//   If an implementation supports key system with attributes on one key system,
-//   it has to support key system with attributes on all key systems supported.
+// |key_system|: A lowercase value in the form of "com.example.somesystem",
+// and can be matched exactly with known DRM key systems of the platform.
+// When |key_system| is an empty string, the return value is an indication for
+// non-encrypted media. See https://w3c.github.io/encrypted-media/#key-system
+//
+// An implementation may choose to support |key_system| with extra attributes,
+// separated by ';', like
+// |com.example.somesystem; attribute_name1="value1"; attribute_name2=value1|.
+// If |key_system| with attributes is not supported by an implementation, it
+// should treat |key_system| as if it contains only the key system, and reject
+// any input containing extra attributes, i.e. it can keep using its existing
+// implementation.
+// When an implementation supports |key_system| with attributes, it has to
+// support all attributes defined by the Starboard version the implementation
+// uses.
+// An implementation should ignore any unknown attributes, and make a decision
+// solely based on the key system and the known attributes. For example, if
+// an implementation supports "com.widevine.alpha", it should also return
+// |kSbMediaSupportTypeProbably| when |key_system| is
+// |com.widevine.alpha; invalid_attribute="invalid_value"|.
+// Currently the only attribute has to be supported is |encryptionscheme|. It
+// reflects the value passed to |encryptionScheme| of
+// MediaKeySystemMediaCapability.
+// This can take value "cenc", "cbcs", or "cbcs-1-9".
+// Empty string is not a valid value for |encryptionscheme| and the
+// implementation should return |kSbMediaSupportTypeNotSupported| when
+// |encryptionscheme| is set to "".
+// The implementation should return |kSbMediaSupportTypeNotSupported| for
+// unknown values of known attributes. For example, if an implementation
+// supports "encryptionscheme" with value "cenc", "cbcs", or "cbcs-1-9", then
+// it should return |kSbMediaSupportTypeProbably| when |key_system| is
+// |com.widevine.alpha; encryptionscheme="cenc"|, and return
+// |kSbMediaSupportTypeNotSupported| when |key_system| is
+// |com.widevine.alpha; encryptionscheme="invalid"|.
+// If an implementation supports key system with attributes on one key system,
+// it has to support key system with attributes on all key systems supported.
+// See: https://wicg.github.io/encrypted-media-encryption-scheme
 SB_EXPORT SbMediaSupportType
 SbMediaCanPlayMimeAndKeySystem(const char* mime, const char* key_system);
 
@@ -688,7 +684,7 @@ SB_EXPORT int SbMediaGetAudioOutputCount();
 // platform or if |output_index| does not exist on this device.
 //
 // |out_configuration|: The variable that holds the audio configuration
-//   information.
+// information.
 SB_EXPORT bool SbMediaGetAudioConfiguration(
     int output_index,
     SbMediaAudioConfiguration* out_configuration);
@@ -703,7 +699,7 @@ typedef enum SbMediaBufferStorageType {
   kSbMediaBufferStorageTypeFile,
 } SbMediaBufferStorageType;
 
-// The media buffer will be allocated using the returned alignment.  Set this to
+// The media buffer will be allocated using the returned alignment. Set this to
 // a larger value may increase the memory consumption of media buffers.
 //
 #if SB_API_VERSION < 16
@@ -718,31 +714,31 @@ SB_EXPORT int SbMediaGetBufferAlignment(SbMediaType type);
 // When the media stack needs more memory to store media buffers, it will
 // allocate extra memory in units returned by SbMediaGetBufferAllocationUnit.
 // This can return 0, in which case the media stack will allocate extra memory
-// on demand.  When SbMediaGetInitialBufferCapacity and this function both
+// on demand. When SbMediaGetInitialBufferCapacity and this function both
 // return 0, the media stack will allocate individual buffers directly using
 // malloc functions.
 SB_EXPORT int SbMediaGetBufferAllocationUnit();
 
 // Specifies the maximum amount of memory used by audio buffers of media source
-// before triggering a garbage collection.  A large value will cause more memory
+// before triggering a garbage collection. A large value will cause more memory
 // being used by audio buffers but will also make the app less likely to
-// re-download audio data.  Note that the app may experience significant
+// re-download audio data. Note that the app may experience significant
 // difficulty if this value is too low.
 SB_EXPORT int SbMediaGetAudioBufferBudget();
 
 // Specifies the duration threshold of media source garbage collection in
-// microseconds.  When the accumulated duration in a source buffer exceeds this
+// microseconds. When the accumulated duration in a source buffer exceeds this
 // value, the media source implementation will try to eject existing buffers
 // from the cache. This is usually triggered when the video being played has a
-// simple content and the encoded data is small.  In such case this can limit
+// simple content and the encoded data is small. In such case this can limit
 // how much is allocated for the book keeping data of the media buffers and
 // avoid OOM of system heap. This should return 170 seconds for most of the
-// platforms.  But it can be further reduced on systems with extremely low
+// platforms. But it can be further reduced on systems with extremely low
 // memory.
 SB_EXPORT int64_t SbMediaGetBufferGarbageCollectionDurationThreshold();
 
 // The amount of memory that will be used to store media buffers allocated
-// during system startup.  To allocate a large chunk at startup helps with
+// during system startup. To allocate a large chunk at startup helps with
 // reducing fragmentation and can avoid failures to allocate incrementally. This
 // can return 0.
 SB_EXPORT int SbMediaGetInitialBufferCapacity();
@@ -751,22 +747,25 @@ SB_EXPORT int SbMediaGetInitialBufferCapacity();
 // must be larger than sum of the video budget and audio budget.
 // This is a soft limit and the app will continue to allocate media buffers even
 // if the accumulated memory used by the media buffers exceeds the maximum
-// buffer capacity.  The allocation of media buffers may only fail when there is
+// buffer capacity. The allocation of media buffers may only fail when there is
 // not enough memory in the system to fulfill the request, under which case the
 // app will be terminated as under other OOM situations.
 //
 // |codec|: the video codec associated with the buffer.
+//
 // |resolution_width|: the width of the video resolution.
+//
 // |resolution_height|: the height of the video resolution.
-// |bits_per_pixel|: the bits per pixel. This value is larger for HDR than non-
-//   HDR video.
+//
+// |bits_per_pixel|: the bits per pixel. This value is larger for HDR
+// than non-HDR video.
 SB_EXPORT int SbMediaGetMaxBufferCapacity(SbMediaVideoCodec codec,
                                           int resolution_width,
                                           int resolution_height,
                                           int bits_per_pixel);
 
 // Extra bytes allocated at the end of a media buffer to ensure that the buffer
-// can be use optimally by specific instructions like SIMD.  Set to 0 to remove
+// can be use optimally by specific instructions like SIMD. Set to 0 to remove
 // any padding.
 //
 #if SB_API_VERSION >= 14
@@ -777,7 +776,7 @@ SB_EXPORT int SbMediaGetBufferPadding(SbMediaType type);
 #endif  // SB_API_VERSION >= 14
 
 // When either SbMediaGetInitialBufferCapacity or SbMediaGetBufferAllocationUnit
-// isn't zero, media buffers will be allocated using a memory pool.  Set the
+// isn't zero, media buffers will be allocated using a memory pool. Set the
 // following variable to true to allocate the media buffer pool memory on demand
 // and return all memory to the system when there is no media buffer allocated.
 // Setting the following value to false results in that Cobalt will allocate
@@ -786,16 +785,19 @@ SB_EXPORT int SbMediaGetBufferPadding(SbMediaType type);
 // media buffers allocated.
 SB_EXPORT bool SbMediaIsBufferPoolAllocateOnDemand();
 
-// The memory used when playing mp4 videos that is not in DASH format.  The
-// resolution of such videos shouldn't go beyond 1080p.  Its value should be
+// The memory used when playing mp4 videos that is not in DASH format. The
+// resolution of such videos shouldn't go beyond 1080p. Its value should be
 // less than the sum of SbMediaGetAudioBufferBudget and
 // 'SbMediaGetVideoBufferBudget(..., 1920, 1080, ...) but not less than 8 MB.
 //
 // |codec|: the video codec associated with the buffer.
+//
 // |resolution_width|: the width of the video resolution.
+//
 // |resolution_height|: the height of the video resolution.
-// |bits_per_pixel|: the bits per pixel. This value is larger for HDR than non-
-//   HDR video.
+//
+// |bits_per_pixel|: the bits per pixel. This value is larger for HDR
+// than non-HDR video.
 SB_EXPORT int SbMediaGetProgressiveBufferBudget(SbMediaVideoCodec codec,
                                                 int resolution_width,
                                                 int resolution_height,
@@ -803,7 +805,7 @@ SB_EXPORT int SbMediaGetProgressiveBufferBudget(SbMediaVideoCodec codec,
 
 // Returns SbMediaBufferStorageType of type |SbMediaStorageTypeMemory| or
 // |SbMediaStorageTypeFile|. For memory storage, the media buffers will be
-// stored in main memory allocated by malloc functions.  For file storage, the
+// stored in main memory allocated by malloc functions. For file storage, the
 // media buffers will be stored in a temporary file in the system cache folder
 // acquired by calling SbSystemGetPath() with "kSbSystemPathCacheDirectory".
 // Note that when its value is "file" the media stack will still allocate memory
@@ -816,16 +818,19 @@ SB_EXPORT SbMediaBufferStorageType SbMediaGetBufferStorageType();
 SB_EXPORT bool SbMediaIsBufferUsingMemoryPool();
 
 // Specifies the maximum amount of memory used by video buffers of media source
-// before triggering a garbage collection.  A large value will cause more memory
+// before triggering a garbage collection. A large value will cause more memory
 // being used by video buffers but will also make app less likely to re-download
-// video data.  Note that the app may experience significant difficulty if this
+// video data. Note that the app may experience significant difficulty if this
 // value is too low.
 //
 // |codec|: the video codec associated with the buffer.
+//
 // |resolution_width|: the width of the video resolution.
+//
 // |resolution_height|: the height of the video resolution.
-// |bits_per_pixel|: the bits per pixel. This value is larger for HDR than non-
-//   HDR video.
+//
+// |bits_per_pixel|: the bits per pixel. This value is larger for HDR
+// than non-HDR video.
 SB_EXPORT int SbMediaGetVideoBufferBudget(SbMediaVideoCodec codec,
                                           int resolution_width,
                                           int resolution_height,
diff --git a/starboard/player.h b/starboard/player.h
index d4582fa6d516..70fe164f5e7e 100644
--- a/starboard/player.h
+++ b/starboard/player.h
@@ -67,8 +67,8 @@ typedef enum SbPlayerState {
 typedef enum SbPlayerError {
   kSbPlayerErrorDecode,
   // The playback capability of the player has changed, likely because of a
-  // change of the system environment.  For example, the system may support vp9
-  // decoding with an external GPU.  When the external GPU is detached, this
+  // change of the system environment. For example, the system may support vp9
+  // decoding with an external GPU. When the external GPU is detached, this
   // error code can signal the app to retry the playback, possibly with h264.
   kSbPlayerErrorCapabilityChanged,
   // The max value of SbPlayer error type. It should always at the bottom
@@ -80,7 +80,7 @@ typedef enum SbPlayerOutputMode {
   // Requests for SbPlayer to produce an OpenGL texture that the client must
   // draw every frame with its graphics rendering. It may be that we get a
   // texture handle, but cannot perform operations like glReadPixels on it if it
-  // is DRM-protected, or it may not support DRM-protected content at all.  When
+  // is DRM-protected, or it may not support DRM-protected content at all. When
   // this output mode is provided to SbPlayerCreate(), the application will be
   // able to pull frames via calls to SbPlayerGetCurrentFrame().
   kSbPlayerOutputModeDecodeToTexture,
@@ -88,7 +88,7 @@ typedef enum SbPlayerOutputMode {
   // Requests for SbPlayer to use a "punch-out" output mode, where video is
   // rendered to the far background, and the graphics plane is automatically
   // composited on top of the video by the platform. The client must punch an
-  // alpha hole out of the graphics plane for video to show through.  In this
+  // alpha hole out of the graphics plane for video to show through. In this
   // case, changing the video bounds must be tightly synchronized between the
   // player and the graphics plane.
   kSbPlayerOutputModePunchOut,
@@ -101,31 +101,31 @@ typedef enum SbPlayerOutputMode {
 // SbPlayerGetPreferredOutputMode().
 typedef struct SbPlayerCreationParam {
   // Provides an appropriate DRM system if the media stream has encrypted
-  // portions.  It will be |kSbDrmSystemInvalid| if the stream does not have
+  // portions. It will be |kSbDrmSystemInvalid| if the stream does not have
   // encrypted portions.
   SbDrmSystem drm_system;
 
 #if SB_API_VERSION >= 15
   // Contains a populated SbMediaAudioStreamInfo if |audio_stream_info.codec|
-  // isn't |kSbMediaAudioCodecNone|.  When |audio_stream_info.codec| is
+  // isn't |kSbMediaAudioCodecNone|. When |audio_stream_info.codec| is
   // |kSbMediaAudioCodecNone|, the video doesn't have an audio track.
   SbMediaAudioStreamInfo audio_stream_info;
   // Contains a populated SbMediaVideoStreamInfo if |video_stream_info.codec|
-  // isn't |kSbMediaVideoCodecNone|.  When |video_stream_info.codec| is
+  // isn't |kSbMediaVideoCodecNone|. When |video_stream_info.codec| is
   // |kSbMediaVideoCodecNone|, the video is audio only.
   SbMediaVideoStreamInfo video_stream_info;
 #else   // SB_API_VERSION >= 15
   // Contains a populated SbMediaAudioSampleInfo if |audio_sample_info.codec|
-  // isn't |kSbMediaAudioCodecNone|.  When |audio_sample_info.codec| is
+  // isn't |kSbMediaAudioCodecNone|. When |audio_sample_info.codec| is
   // |kSbMediaAudioCodecNone|, the video doesn't have an audio track.
   SbMediaAudioSampleInfo audio_sample_info;
   // Contains a populated SbMediaVideoSampleInfo if |video_sample_info.codec|
-  // isn't |kSbMediaVideoCodecNone|.  When |video_sample_info.codec| is
+  // isn't |kSbMediaVideoCodecNone|. When |video_sample_info.codec| is
   // |kSbMediaVideoCodecNone|, the video is audio only.
   SbMediaVideoSampleInfo video_sample_info;
 #endif  // SB_API_VERSION >= 15
 
-  // Selects how the decoded video frames will be output.  For example,
+  // Selects how the decoded video frames will be output. For example,
   // |kSbPlayerOutputModePunchOut| indicates that the decoded video frames will
   // be output to a background video layer by the platform, and
   // |kSbPlayerOutputDecodeToTexture| indicates that the decoded video frames
@@ -138,11 +138,11 @@ typedef struct SbPlayerCreationParam {
 // data may come from multiple sources.
 typedef enum SbPlayerSampleSideDataType {
   // The side data comes from the BlockAdditional data in the Matroska/Webm
-  // container, as specified in
-  // https://tools.ietf.org/id/draft-lhomme-cellar-matroska-03.html#rfc.section.7.3.39
-  // and https://www.webmproject.org/docs/container/#BlockAdditional.
+  // container.
   // The first 8 bytes of the data contains the value of BlockAddID in big
-  // endian format, followed by the content of BlockAdditional.
+  // endian format, followed by the content of BlockAdditional. See:
+  //  * https://datatracker.ietf.org/doc/draft-lhomme-cellar-matroska/03
+  //  * https://www.webmproject.org/docs/container/#BlockAdditional
   kMatroskaBlockAdditional,
 } SbPlayerSampleSideDataType;
 
@@ -169,7 +169,7 @@ typedef struct SbPlayerSampleInfo {
 
   // Points to an array of side data for the input, when available.
   SbPlayerSampleSideData* side_data;
-  // The number of side data pointed by |side_data|.  It should be set to 0 if
+  // The number of side data pointed by |side_data|. It should be set to 0 if
   // there is no side data for the input.
   int side_data_count;
 
@@ -230,11 +230,11 @@ typedef struct SbPlayerInfo2 {
   // the player.
   int corrupted_video_frames;
 
-  // The rate of playback.  The video is played back in a speed that is
-  // proportional to this.  By default it is 1.0 which indicates that the
-  // playback is at normal speed.  When it is greater than one, the video is
-  // played in a faster than normal speed.  When it is less than one, the video
-  // is played in a slower than normal speed.  Negative speeds are not
+  // The rate of playback. The video is played back in a speed that is
+  // proportional to this. By default it is 1.0 which indicates that the
+  // playback is at normal speed. When it is greater than one, the video is
+  // played in a faster than normal speed. When it is less than one, the video
+  // is played in a slower than normal speed. Negative speeds are not
   // supported.
   double playback_rate;
 #if SB_API_VERSION >= 15
@@ -274,7 +274,9 @@ typedef void (*SbPlayerStatusFunc)(SbPlayer player,
                                    int ticket);
 
 // Callback for player errors, that may set a |message|.
+//
 // |error|: indicates the error code.
+//
 // |message|: provides specific informative diagnostic message about the error
 //            condition encountered. It is ok for the message to be an empty
 //            string or NULL if no information is available.
@@ -283,7 +285,7 @@ typedef void (*SbPlayerErrorFunc)(SbPlayer player,
                                   SbPlayerError error,
                                   const char* message);
 
-// Callback to free the given sample buffer data.  When more than one buffer
+// Callback to free the given sample buffer data. When more than one buffer
 // are sent in SbPlayerWriteSample(), the implementation only has to call this
 // callback with |sample_buffer| points to the first buffer.
 typedef void (*SbPlayerDeallocateSampleFunc)(SbPlayer player,
@@ -340,79 +342,79 @@ static inline bool SbPlayerIsValid(SbPlayer player) {
 //   must not cause a crash.
 //
 // |window|: The window that will display the player. |window| can be
-//   |kSbWindowInvalid| for platforms where video is only displayed on a
-//   particular window that the underlying implementation already has access to.
+// |kSbWindowInvalid| for platforms where video is only displayed on a
+// particular window that the underlying implementation already has access to.
 //
 // |video_codec|: The video codec used for the player. If |video_codec| is
-//   |kSbMediaVideoCodecNone|, the player is an audio-only player. If
-//   |video_codec| is any other value, the player is an audio/video decoder.
-//   This can be set to |kSbMediaVideoCodecNone| to play a video with only an
-//   audio track.
+// |kSbMediaVideoCodecNone|, the player is an audio-only player. If
+// |video_codec| is any other value, the player is an audio/video decoder.
+// This can be set to |kSbMediaVideoCodecNone| to play a video with only an
+// audio track.
 //
 // |audio_codec|: The audio codec used for the player. The caller must provide a
-//   populated |audio_sample_info| if audio codec is |kSbMediaAudioCodecAac|.
-//   Can be set to |kSbMediaAudioCodecNone| to play a video without any audio
-//   track.  In such case |audio_sample_info| must be NULL.
+// populated |audio_sample_info| if audio codec is |kSbMediaAudioCodecAac|.
+// Can be set to |kSbMediaAudioCodecNone| to play a video without any audio
+// track. In such case |audio_sample_info| must be NULL.
 //
 // |drm_system|: If the media stream has encrypted portions, then this
-//   parameter provides an appropriate DRM system, created with
-//   |SbDrmCreateSystem()|. If the stream does not have encrypted portions,
-//   then |drm_system| may be |kSbDrmSystemInvalid|.
+// parameter provides an appropriate DRM system, created with
+// |SbDrmCreateSystem()|. If the stream does not have encrypted portions,
+// then |drm_system| may be |kSbDrmSystemInvalid|.
 //
 // |audio_sample_info|: Note that the caller must provide a populated
-//   |audio_sample_info| if the audio codec is |kSbMediaAudioCodecAac|.
-//   Otherwise, |audio_sample_info| can be NULL. See media.h for the format of
-//   the |SbMediaAudioSampleInfo| struct.
+// |audio_sample_info| if the audio codec is |kSbMediaAudioCodecAac|.
+// Otherwise, |audio_sample_info| can be NULL. See media.h for the format of
+// the |SbMediaAudioSampleInfo| struct.
 //
-//   Note that |audio_specific_config| is a pointer and the content it points to
-//   is no longer valid after this function returns.  The implementation has to
-//   make a copy of the content if it is needed after the function returns.
+// Note that |audio_specific_config| is a pointer and the content it points to
+// is no longer valid after this function returns. The implementation has to
+// make a copy of the content if it is needed after the function returns.
 //
 // |max_video_capabilities|: This string communicates the max video capabilities
-//   required to the platform. The web app will not provide a video stream
-//   exceeding the maximums described by this parameter. Allows the platform to
-//   optimize playback pipeline for low quality video streams if it knows that
-//   it will never adapt to higher quality streams. The string uses the same
-//   format as the string passed in to SbMediaCanPlayMimeAndKeySystem(), for
-//   example, when it is set to "width=1920; height=1080; framerate=15;", the
-//   video will never adapt to resolution higher than 1920x1080 or frame per
-//   second higher than 15 fps. When the maximums are unknown, this will be set
-//   to NULL.
+// required to the platform. The web app will not provide a video stream
+// exceeding the maximums described by this parameter. Allows the platform to
+// optimize playback pipeline for low quality video streams if it knows that
+// it will never adapt to higher quality streams. The string uses the same
+// format as the string passed in to SbMediaCanPlayMimeAndKeySystem(), for
+// example, when it is set to "width=1920; height=1080; framerate=15;", the
+// video will never adapt to resolution higher than 1920x1080 or frame per
+// second higher than 15 fps. When the maximums are unknown, this will be set
+// to NULL.
 //
 // |sample_deallocator_func|: If not |NULL|, the player calls this function
-//   on an internal thread to free the sample buffers passed into
-//   SbPlayerWriteSample().
+// on an internal thread to free the sample buffers passed into
+// SbPlayerWriteSample().
 //
 // |decoder_status_func|: If not |NULL|, the decoder calls this function on an
-//   internal thread to provide an update on the decoder's status. No work
-//   should be done on this thread. Rather, it should just signal the client
-//   thread interacting with the decoder.
+// internal thread to provide an update on the decoder's status. No work
+// should be done on this thread. Rather, it should just signal the client
+// thread interacting with the decoder.
 //
 // |player_status_func|: If not |NULL|, the player calls this function on an
-//   internal thread to provide an update on the playback status. No work
-//   should be done on this thread. Rather, it should just signal the client
-//   thread interacting with the decoder.
+// internal thread to provide an update on the playback status. No work
+// should be done on this thread. Rather, it should just signal the client
+// thread interacting with the decoder.
 //
 // |player_error_func|: If not |NULL|, the player calls this function on an
-//   internal thread to provide an update on the error status. This callback is
-//   responsible for setting the media error message.
+// internal thread to provide an update on the error status. This callback is
+// responsible for setting the media error message.
 //
 // |context|: This is passed to all callbacks and is generally used to point
-//   at a class or struct that contains state associated with the player.
-//
-// |output_mode|: Selects how the decoded video frames will be output.  For
-//   example, kSbPlayerOutputModePunchOut indicates that the decoded video
-//   frames will be output to a background video layer by the platform, and
-//   kSbPlayerOutputDecodeToTexture indicates that the decoded video frames
-//   should be made available for the application to pull via calls to
-//   SbPlayerGetCurrentFrame().
-//
-// |provider|: Only present in Starboard version 3 and up.  If not |NULL|,
-//   then when output_mode == kSbPlayerOutputModeDecodeToTexture, the player MAY
-//   use the provider to create SbDecodeTargets on the renderer thread. A
-//   provider may not always be needed by the player, but if it is needed, and
-//   the provider is not given, the player will fail by returning
-//   |kSbPlayerInvalid|.
+// at a class or struct that contains state associated with the player.
+//
+// |output_mode|: Selects how the decoded video frames will be outputFor
+// example, kSbPlayerOutputModePunchOut indicates that the decoded video
+// frames will be output to a background video layer by the platform, and
+// kSbPlayerOutputDecodeToTexture indicates that the decoded video frames
+// should be made available for the application to pull via calls to
+// SbPlayerGetCurrentFrame().
+//
+// |provider|: Only present in Starboard version 3 and up. If not |NULL|,
+// then when output_mode == kSbPlayerOutputModeDecodeToTexture, the player MAY
+// use the provider to create SbDecodeTargets on the renderer thread. A
+// provider may not always be needed by the player, but if it is needed, and
+// the provider is not given, the player will fail by returning
+// |kSbPlayerInvalid|.
 //
 // If |NULL| is passed to any of the callbacks (|sample_deallocator_func|,
 // |decoder_status_func|, |player_status_func|, or |player_error_func| if it
@@ -428,13 +430,13 @@ SbPlayerCreate(SbWindow window,
                SbDecodeTargetGraphicsContextProvider* context_provider);
 
 // Returns the preferred output mode of the implementation when a video
-// described by |creation_param| is played.  It is assumed that it is okay to
+// described by |creation_param| is played. It is assumed that it is okay to
 // call SbPlayerCreate() with the same video described by |creation_param|,
 // with its |output_mode| member replaced by the returned output mode.
 // When the caller has no preference on the output mode, it will set
 // |creation_param->output_mode| to |kSbPlayerOutputModeInvalid|, and the
 // implementation can return its preferred output mode based on the information
-// contained in |creation_param|.  The caller can also set
+// contained in |creation_param|. The caller can also set
 // |creation_param->output_mode| to its preferred output mode, and the
 // implementation should return the same output mode if it is supported,
 // otherwise the implementation should return an output mode that it is
@@ -450,11 +452,12 @@ SbPlayerGetPreferredOutputMode(const SbPlayerCreationParam* creation_param);
 // Destroys |player|, freeing all associated resources.
 //  * Upon calling this method, there should be one call to the player status
 //    callback (i.e. |player_status_func| used in the creation of the player)
-//    which indicates the player is destroyed. Note, the callback has to be
-//    in-flight when SbPlayerDestroyed is called.
+//    which indicates the player is destroyed. Note, the callback has to
+//    be in-flight when SbPlayerDestroyed is called.
 //  * No more other callbacks should be issued after this function returns.
 //  * It is not allowed to pass |player| into any other |SbPlayer| function
 //    once SbPlayerDestroy has been called on that player.
+//
 // |player|: The player to be destroyed. Must not be |kSbPlayerInvalid|.
 SB_EXPORT void SbPlayerDestroy(SbPlayer player);
 
@@ -463,29 +466,29 @@ SB_EXPORT void SbPlayerDestroy(SbPlayer player);
 // The player should restart playback once it can display the frame at
 // |seek_to_timestamp|, or the closest it can get. (Some players can only seek
 // to I-Frames, for example.)
-//
-// - Seek must be called before samples are sent when starting playback for
-//   the first time, or the client never receives the
-//   |kSbPlayerDecoderStateNeedsData| signal.
-// - A call to seek may interrupt another seek.
-// - After this function is called, the client should not send any more audio
-//   or video samples until |SbPlayerDecoderStatusFunc| is called back with
-//   |kSbPlayerDecoderStateNeedsData| for each required media type.
-//   |SbPlayerDecoderStatusFunc| is the |decoder_status_func| callback function
-//   that was specified when the player was created (SbPlayerCreate).
+//  * Seek must be called before samples are sent when starting playback for
+//    the first time, or the client never receives the
+//    |kSbPlayerDecoderStateNeedsData| signal.
+//  * A call to seek may interrupt another seek.
+//  * After this function is called, the client should not send any more audio
+//    or video samples until |SbPlayerDecoderStatusFunc| is called back with
+//    |kSbPlayerDecoderStateNeedsData| for each required media type.
+//    |SbPlayerDecoderStatusFunc| is the |decoder_status_func| callback function
+//    that was specified when the player was created (SbPlayerCreate).
 //
 // |player|: The SbPlayer in which the seek operation is being performed.
-//   Must not be |kSbPlayerInvalid|.
-
+// Must not be |kSbPlayerInvalid|.
+//
 // |seek_to_timestamp|: The frame at which playback should begin.
-// |ticket|: A user-supplied unique ID that is be passed to all subsequent
-//   |SbPlayerDecoderStatusFunc| calls. (That is the |decoder_status_func|
-//   callback function specified when calling SbPlayerCreate.)
-//
-//   The |ticket| value is used to filter calls that may have been in flight
-//   when SbPlayerSeek was called. To be very specific, once SbPlayerSeek has
-//   been called with ticket X, a client should ignore all
-//   |SbPlayerDecoderStatusFunc| calls that do not pass in ticket X.
+//
+// |ticket|: A user-supplied unique ID that is to be passed to all subsequent
+// |SbPlayerDecoderStatusFunc| calls. (That is the |decoder_status_func|
+// callback function specified when calling SbPlayerCreate.)
+//
+// The |ticket| value is used to filter calls that may have been in flight
+// when SbPlayerSeek was called. To be very specific, once SbPlayerSeek has
+// been called with ticket X, a client should ignore all
+// |SbPlayerDecoderStatusFunc| calls that do not pass in ticket X.
 #if SB_API_VERSION >= 15
 SB_EXPORT void SbPlayerSeek(SbPlayer player,
                             int64_t seek_to_timestamp,
@@ -507,19 +510,21 @@ SB_EXPORT void SbPlayerSeek2(SbPlayer player,
 // SbPlayerWriteSamples() allows writing of multiple samples in one call.
 //
 // |player|: The player to which the sample is written. Must not be
-//   |kSbPlayerInvalid|.
-
+// |kSbPlayerInvalid|.
+//
 // |sample_type|: The type of sample being written. See the |SbMediaType|
-//   enum in media.h.
+// enum in media.h.
+//
 // |sample_infos|: A pointer to an array of SbPlayerSampleInfo with
-//   |number_of_sample_infos| elements, each holds the data for an sample, i.e.
-//   a sequence of whole NAL Units for video, or a complete audio frame.
-//   |sample_infos| cannot be assumed to live past the call into
-//   SbPlayerWriteSamples(), so it must be copied if its content will be used
-//   after SbPlayerWriteSamples() returns.
+// |number_of_sample_infos| elements, each holds the data for an sample, i.e.
+// a sequence of whole NAL Units for video, or a complete audio frame.
+// |sample_infos| cannot be assumed to live past the call into
+// SbPlayerWriteSamples(), so it must be copied if its content will be used
+// after SbPlayerWriteSamples() returns.
+//
 // |number_of_sample_infos|: Specify the number of samples contained inside
-//   |sample_infos|.  It has to be at least one, and at most the return value
-//   of SbPlayerGetMaximumNumberOfSamplesPerWrite().
+// |sample_infos|. It has to be at least one, and at most the return value
+// of SbPlayerGetMaximumNumberOfSamplesPerWrite().
 #if SB_API_VERSION >= 15
 SB_EXPORT void SbPlayerWriteSamples(SbPlayer player,
 #else   // SB_API_VERSION >= 15
@@ -538,8 +543,9 @@ SB_EXPORT void SbPlayerWriteSample2(SbPlayer player,
 // SbPlayerWriteSamples() will always be called with one sample.
 //
 // |player|: The player for which the number is retrieved.
+//
 // |sample_type|: The type of sample for which the number is retrieved. See the
-//   |SbMediaType| enum in media.h.
+// |SbMediaType| enum in media.h.
 SB_EXPORT int SbPlayerGetMaximumNumberOfSamplesPerWrite(
     SbPlayer player,
     SbMediaType sample_type);
@@ -550,13 +556,14 @@ SB_EXPORT int SbPlayerGetMaximumNumberOfSamplesPerWrite(
 // contents, after a call to SbPlayerSeek.
 //
 // |player|: The player to which the marker is written.
+//
 // |stream_type|: The type of stream for which the marker is written.
 SB_EXPORT void SbPlayerWriteEndOfStream(SbPlayer player,
                                         SbMediaType stream_type);
 
 // Sets the player bounds to the given graphics plane coordinates. The changes
 // do not take effect until the next graphics frame buffer swap. The default
-// bounds for a player is the full screen.  This function is only relevant when
+// bounds for a player is the full screen. This function is only relevant when
 // the |player| is created with the kSbPlayerOutputModePunchOut output mode, and
 // if this is not the case then this function call can be ignored.
 //
@@ -567,12 +574,17 @@ SB_EXPORT void SbPlayerWriteEndOfStream(SbPlayer player,
 // with such frequent calls.
 //
 // |player|: The player that is being resized. Must not be |kSbPlayerInvalid|.
-// |z_index|: The z-index of the player.  When the bounds of multiple players
-//            are overlapped, the one with larger z-index will be rendered on
-//            top of the ones with smaller z-index.
+//
+// |z_index|: The z-index of the player. When the bounds of multiple players
+// are overlapped, the one with larger z-index will be rendered on
+// top of the ones with smaller z-index.
+//
 // |x|: The x-coordinate of the upper-left corner of the player.
+//
 // |y|: The y-coordinate of the upper-left corner of the player.
+//
 // |width|: The width of the player, in pixels.
+//
 // |height|: The height of the player, in pixels.
 SB_EXPORT void SbPlayerSetBounds(SbPlayer player,
                                  int z_index,
@@ -581,12 +593,12 @@ SB_EXPORT void SbPlayerSetBounds(SbPlayer player,
                                  int width,
                                  int height);
 
-// Set the playback rate of the |player|.  |rate| is default to 1.0 which
-// indicates the playback is at its original speed.  A |rate| greater than one
-// will make the playback faster than its original speed.  For example, when
+// Set the playback rate of the |player|. |rate| is default to 1.0 which
+// indicates the playback is at its original speed. A |rate| greater than one
+// will make the playback faster than its original speed. For example, when
 // |rate| is 2, the video will be played at twice the speed as its original
-// speed.  A |rate| less than 1.0 will make the playback slower than its
-// original speed.  When |rate| is 0, the playback will be paused.
+// speed. A |rate| less than 1.0 will make the playback slower than its
+// original speed. When |rate| is 0, the playback will be paused.
 // The function returns true when the playback rate is set to |playback_rate| or
 // to a rate that is close to |playback_rate| which the implementation supports.
 // It returns false when the playback rate is unchanged, this can happen when
@@ -598,10 +610,11 @@ SB_EXPORT bool SbPlayerSetPlaybackRate(SbPlayer player, double playback_rate);
 // Sets the player's volume.
 //
 // |player|: The player in which the volume is being adjusted. Must not be
-//   |kSbPlayerInvalid|.
+// |kSbPlayerInvalid|.
+//
 // |volume|: The new player volume. The value must be between |0.0| and |1.0|,
-//   inclusive. A value of |0.0| means that the audio should be muted, and a
-//   value of |1.0| means that it should be played at full volume.
+// inclusive. A value of |0.0| means that the audio should be muted, and a
+// value of |1.0| means that it should be played at full volume.
 SB_EXPORT void SbPlayerSetVolume(SbPlayer player, double volume);
 
 // Gets a snapshot of the current player state and writes it to
@@ -609,9 +622,9 @@ SB_EXPORT void SbPlayerSetVolume(SbPlayer player, double volume);
 // expected to be inexpensive.
 //
 // |player|: The player about which information is being retrieved. Must not be
-//   |kSbPlayerInvalid|.
+// |kSbPlayerInvalid|.
+//
 // |out_player_info|: The information retrieved for the player.
-
 #if SB_API_VERSION >= 15
 SB_EXPORT void SbPlayerGetInfo(SbPlayer player, SbPlayerInfo* out_player_info);
 #else   // SB_API_VERSION >= 15
@@ -621,9 +634,9 @@ SB_EXPORT void SbPlayerGetInfo2(SbPlayer player,
 
 // Given a player created with the kSbPlayerOutputModeDecodeToTexture
 // output mode, it will return a SbDecodeTarget representing the current frame
-// to be rasterized.  On GLES systems, this function must be called on a
+// to be rasterized. On GLES systems, this function must be called on a
 // thread with an EGLContext current, and specifically the EGLContext that will
-// be used to eventually render the frame.  If this function is called with a
+// be used to eventually render the frame. If this function is called with a
 // |player| object that was created with an output mode other than
 // kSbPlayerOutputModeDecodeToTexture, kSbDecodeTargetInvalid is returned.
 //
@@ -633,58 +646,56 @@ SB_EXPORT SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer player);
 // Returns the audio configurations used by |player|.
 //
 // Returns true when |out_audio_configuration| is filled with the information of
-// the configuration of the audio output devices used by |player|.  Returns
+// the configuration of the audio output devices used by |player|. Returns
 // false for |index| 0 to indicate that there is no audio output for this
-// |player|.  Returns false for |index| greater than 0 to indicate that there
+// |player|. Returns false for |index| greater than 0 to indicate that there
 // are no more audio output configurations other than the ones already returned.
 //
 // The app will use the information returned to determine audio related
 // behaviors, like:
-//
-//   Audio Write Duration: Audio write duration is how far past the current
-//       playback position the app will write audio samples. The app will write
-//       all samples between |current_playback_position| and
-//       |current_playback_position| + |audio_write_duration|, as soon as they
-//       are available.
-//
-//       |audio_write_duration| will be to `kSbPlayerWriteDurationLocal` when
-//       all audio configurations linked to |player| is local, or if there isn't
-//       any audio output.  It will be set to `kSbPlayerWriteDurationRemote` for
-//       remote or wireless audio outputs, i.e. one of
-//       `kSbMediaAudioConnectorBluetooth` or `kSbMediaAudioConnectorRemote*`.
-//
-//       The app only guarantees to write |audio_write_duration| past
-//       |current_playback_position|, but the app is free to write more samples
-//       than that.  So the platform shouldn't rely on this for flow control.
-//       The platform should achieve flow control by sending
-//       `kSbPlayerDecoderStateNeedsData` less frequently.
-//
-//       The platform is responsible for guaranteeing that when only
-//       |audio_write_duration| audio samples are written at a time, no playback
-//       issues occur (such as transient or indefinite hanging).
+//  * Audio Write Duration: Audio write duration is how far past the current
+//    playback position the app will write audio samples. The app will write
+//    all samples between |current_playback_position| and
+//    |current_playback_position| + |audio_write_duration|, as soon as they
+//    are available.
+//  * |audio_write_duration| will be to |kSbPlayerWriteDurationLocal| when
+//    all audio configurations linked to |player| is local, or if there isn't
+//    any audio output. It will be set to |kSbPlayerWriteDurationRemote| for
+//    remote or wireless audio outputs, i.e. one of
+//    |kSbMediaAudioConnectorBluetooth| or |kSbMediaAudioConnectorRemote*|.
+//  * The app only guarantees to write |audio_write_duration| past
+//    |current_playback_position|, but the app is free to write more samples
+//    than that. So the platform shouldn't rely on this for flow control.
+//    The platform should achieve flow control by sending
+//    |kSbPlayerDecoderStateNeedsData| less frequently.
+//  * The platform is responsible for guaranteeing that when only
+//    |audio_write_duration| audio samples are written at a time, no playback
+//    issues occur (such as transient or indefinite hanging).
 //
 // The audio configurations should be available as soon as possible, and they
-// have to be available when the |player| is at `kSbPlayerStatePresenting`,
+// have to be available when the |player| is at |kSbPlayerStatePresenting|,
 // unless the audio codec is |kSbMediaAudioCodecNone| or there's no written
 // audio inputs.
 //
-// The app will set |audio_write_duration| to `kSbPlayerWriteDurationLocal`
+// The app will set |audio_write_duration| to |kSbPlayerWriteDurationLocal|
 // when the audio configuration isn't available (i.e. the function returns false
-// when index is 0).  The platform has to make the audio configuration
+// when index is 0). The platform has to make the audio configuration
 // available immediately after the SbPlayer is created, if it expects the app to
 // treat the platform as using wireless audio outputs.
 //
 // Once at least one audio configurations are returned, the return values and
-// their orders shouldn't change during the life time of |player|.  The platform
+// their orders shouldn't change during the life time of |player|. The platform
 // may inform the app of any changes by sending
-// `kSbPlayerErrorCapabilityChanged` to request a playback restart.
+// |kSbPlayerErrorCapabilityChanged| to request a playback restart.
 //
 // |player|: The player about which information is being retrieved. Must not be
-//   |kSbPlayerInvalid|.
-// |index|: The index of the audio output configuration.  Must be greater than
-//   or equal to 0.
+// |kSbPlayerInvalid|.
+//
+// |index|: The index of the audio output configuration. Must be greater than
+// or equal to 0.
+//
 // |out_audio_configuration|: The information about the audio output, refer to
-//   |SbMediaAudioConfiguration| for more details.  Must not be NULL.
+// |SbMediaAudioConfiguration| for more details. Must not be NULL.
 #if SB_API_VERSION >= 15
 SB_EXPORT bool SbPlayerGetAudioConfiguration(
     SbPlayer player,