VPLAY-11339: [DOC] eAAMPConfig_NativeCCRendering and setTextStyleOptions

AAMP-UVE-API.md

@@ -2716,28 +2716,47 @@ XREReceiver.onEvent("onDecoderAvailable", { decoderHandle: null });
 
 ## Inband (CEA608/708) Closed Caption Management (modern UVE/AAMP API)
 
-Configure nativeCCRendering to true to signal use of subtec for caption rendering. 
-```
-player.initConfig( { nativeCCRendering: true } );
+Whether AAMP manages CC visibility and styles directly depends on the platform.
+On **X1 devices**, CC is owned by **XREReceiver**, which runs independently of AAMP.
+`nativeCCRendering` must remain `false` (the default) so AAMP does not interfere with
+XREReceiver's trickplay muting, parental control gating, or style management.
+On **platforms without XREReceiver**, the app must set `nativeCCRendering: true` to
+hand AAMP ownership of the CC lifecycle via `PlayerCCManager`. Apps must refrain from
+using AAMP CC APIs when `nativeCCRendering` is set to false.
 
+### Platform Summary
+
+| Device Class | `nativeCCRendering` | `player.setTextStyleOptions` |
+|---|---|---|
+| X1 (XREReceiver present) | `false` (default — do not set to true) | Do **not** call AAMP CC APIs; XREReceiver owns CC visibility and styling and applies guide-configured styles automatically |
+| Non-XRE but pre-ENT-OS | `true` (must be explicitly enabled) | Required to apply caption styling; guide settings are not automatically propagated |
+| ENT-OS (with Text Track plugin) | `true` | Not required; Text Track plugin automatically maps guide-configured caption styling |
+
+### Configuration
+
+For non-XRE platforms, opt AAMP into managing CC before calling `load()`:
+```js
+player.initConfig( { nativeCCRendering: true } );
 ```
-Toggle CC display on or off at runtime:
-```
-player.setClosedCaptionStatus(true); // show captions (off by default)
-player.setClosedCaptionStatus(false); // mute captions
-```
-Get/Set CC track at runtime:
-```
-player.getTextTrack(); // returns json object listing track attributes
-player.setTextTrack(trackIdentifier);
 
-Get/Set CC style options at runtime
+### Runtime CC Control
+
+Toggle CC display on or off:
+```js
+player.setClosedCaptionStatus(true);  // show captions (off by default)
+player.setClosedCaptionStatus(false); // hide captions
 ```
-player.getTextStyleOptions(); // returns JSON object reflecting currently styling options
-player.setTextStyleOptions(options); // TODO: include examples known to work with RDK CC Manager and/or subtec
 
-On newer devices there is no need to call setTextStyleOptions, as the Text Track plugin will automatically map guide-configured caption styling.
+Get/Set CC track:
+```js
+player.getTextTrack();             // returns JSON object listing track attributes
+player.setTextTrack(trackIdentifier);
+```
 
+Get/Set CC style options:
+```js
+player.getTextStyleOptions();      // returns JSON object reflecting current styling options
+player.setTextStyleOptions(options); // set styling options (see setTextStyleOptions API for format)
 ```
 
 ---

AampConfig.h

@@ -152,7 +152,18 @@ typedef enum
 	eAAMPConfig_BulkTimedMetaReport, 					/**< Enabled Bulk event reporting for TimedMetadata*/
 	eAAMPConfig_BulkTimedMetaReportLive,					/**< Enabled Bulk TimedMetadata event reporting for live stream */
 	eAAMPConfig_AvgBWForABR,						/**< Enables usage of AverageBandwidth if available for ABR */
-	eAAMPConfig_NativeCCRendering,						/**< If native CC rendering to be supported */
+	eAAMPConfig_NativeCCRendering,					/**< Controls whether AAMP manages CC visibility/styles
+														directly via PlayerCCManager (true), or defers to an
+														external CC controller such as XREReceiver (false).
+														Default: false.
+														On X1 platforms XREReceiver owns CC; set to false so
+														AAMP does not interfere with trickplay muting, parental
+														control gating, or CC track selection.
+														On platforms without XREReceiver, set to true so AAMP
+														takes over the full CC lifecycle.
+														Note: Regardless of this flag, AAMP's CC APIs still
+														route through PlayerCCManager and apps must refrain from
+														using them when the flag is set to false.*/
 	eAAMPConfig_Subtec_subtitle,						/**< Enable subtec-based subtitles */
 	eAAMPConfig_WebVTTNative,						/**< Enable subtec-based subtitles */
 	eAAMPConfig_AsyncTune,						 	/**< To enable Asynchronous tune */

main_aamp.cpp

@@ -2811,7 +2811,27 @@ std::string PlayerInstanceAAMP::GetAppName()
 }
 
 /**
- *  @brief Enable/disable the native CC rendering feature
+ *  @brief Enable or disable AAMP-managed CC rendering.
+ *
+ *  When enable is true, AAMP takes ownership of the CC rendering lifecycle
+ *  via PlayerCCManager: initialization on first frame, trickplay muting,
+ *  parental control gating (SERVICE_PIN_LOCKED events), CEA-608/708 track
+ *  selection, and session teardown on stop.
+ *
+ *  When enable is false (the default), AAMP does not drive CC rendering
+ *  behaviour or policy decisions (e.g. trickplay muting, parental-control
+ *  integration, or CC-specific teardown). Internal components such as
+ *  PlayerCCManager may still be initialised but internally it will be
+ *  using PlayerFakeCCManager.
+ *
+ *  This is the correct setting for X1 platforms where XREReceiver controls
+ *  CC independently of AAMP. Enabling it on X1 would cause AAMP to overlap
+ *  with XREReceiver's CC management responsibilities.
+ *
+ *  Must be called before Tune() to take effect for a given session.
+ *
+ *  @param[in] enable  true  — AAMP manages CC (platforms without XREReceiver)
+ *                     false — external controller manages CC (X1 / XREReceiver)
  */
 void PlayerInstanceAAMP::SetNativeCCRendering(bool enable)
 {