Package com.castlabs.sdk.debug

# Class DebugPlugin

java.lang.Object
com.castlabs.android.Plugin
com.castlabs.sdk.debug.DebugPlugin

public class DebugPlugin extends Plugin
This plugin can be registered with `PlayerSDK.register(Plugin)` to enable additional debug logs.

Instances of the debug plugin can be created using the `DebugPlugin.Builder`. The builder is also used to configure the plugin and its logging capabilities. For example:

     PlayerSDK.register(new DebugPlugin.Builder()
         .logOpenBundle(true)
         .get()
     );

The debug plugin does also expose a rate limiter that can be enabled with `DebugPlugin.Builder.enableRateLimiter(boolean, long)` and accessed at runtime with

            DebugPlugin debugPlugin = PlayerSDK.getPlugin(DebugPlugin.class);
                    if (debugPlugin != null) {
                            RateLimiter rateLimiter = debugPlugin.getRateLimiter();
          }

The features of this plugin can be enabled or disabled after it registered to the `PlayerSDK`. For example to enable the rate limiter:

     DebugPlugin debugPlugin = PlayerSDK.getPlugin(DebugPlugin.class);
     if (debugPlugin != null) {
                    debugPlugin.setRateLimiterEnabled(true);
     }

Or the debug overlay could be shown or hidden after registration. The position of the debug overlay could also be changed. For example:

     debugPlugin.setDebugOverlayPosition(debugOverlayPosition);
     debugPlugin.hideDebugOverlay();

The debug overlay should be enabled before registration in order to show, hide or change the position of it.

Since:
  4.1.11

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `DebugPlugin.Builder`
  Use this builder to create new instances of the `DebugPlugin`.
  `static enum`
  `DebugPlugin.DebugOverlayPosition`
  Enum representing the possible positions of the debug overlay.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEBUG_OVERLAY_ID`
  The ID of the debug overlay view.
  `final boolean`
  `enableDebugOverlay`
  If true, the debug overlay is enabled.
  `final long`
  `initialRateLimitBps`
  The initial rate limit in bits per second.
  `final long`
  `logAVSyncThresholdUs`
  The threshold in microseconds for logging AV sync values.
  `final long`
  `logMeanAndDeviationPeriodUs`
  The period in microseconds for logging mean and deviation of AV sync values.
  `final List<Integer>`
  `logRequestTypes`
  A list of request types to log.
  `final List<Integer>`
  `logResponseTypes`
  A list of response types to log.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static DebugPlayerControllerComponent`
  `getDebugComponent(PlayerController playerController)`
  Gets the `DebugPlayerControllerComponent` associated with the given `PlayerController`.
  `DebugPlugin.DebugOverlayPosition`
  `getDebugOverlayPosition()`
  Getter for debugOverlayPosition
  `String`
  `getId()`
  `boolean`
  `getLogAudioRendererEvents()`
  Getter for logAudioRendererEvents
  `boolean`
  `getLogDecoderCounters()`
  Getter for logDecoderCounters
  `boolean`
  `getLogDownloadCanceled()`
  Getter for logDownloadCanceled
  `boolean`
  `getLogDownloadCompleted()`
  Getter for logDownloadCompleted
  `boolean`
  `getLogDownloadError()`
  Getter for logDownloadError
  `boolean`
  `getLogDownloadStarted()`
  Getter for logDownloadStarted
  `boolean`
  `getLogDownloadUpstreamDiscarded()`
  Getter for logDownloadUpstreamDiscarded
  `boolean`
  `getLogLoadControl()`
  Getter for logLoadControl
  `boolean`
  `getLogOpenBundle()`
  Getter for logOpenBundle
  `boolean`
  `getLogPeriodInfo()`
  Getter for logPeriodInfo
  `boolean`
  `getLogSupportedDrm()`
  Getter for logSupportedDrm
  `boolean`
  `getLogTimingDebugInfo()`
  Getter for logTimingDebugInfo
  `boolean`
  `getLogTransferInfo()`
  Getter for logTransferInfo
  `boolean`
  `getLogVideoFrameMetadata()`
  Getter for logging video frame metadata
  `boolean`
  `getLogVideoRendererEvents()`
  Getter for logVideoRendererEvents
  `static OverlayControllerComponent`
  `getOverlayController(PlayerController playerController)`
  Gets the `OverlayControllerComponent` associated with the given `PlayerController`.
  `RateLimiter`
  `getRateLimiter()`
  Returns the rate limiter if it was enabled or null
  `boolean`
  `getRateLimiterEnabled()`
  Getter for rateLimiterEnabled
  `DebugMediaCodecAdapterFactory`
  `getVideoCodecAdapterFactory()`
  Returns the debug media codec adapter factory if it was enabled or null.
  `void`
  `setDebugOverlayPosition(DebugPlugin.DebugOverlayPosition debugOverlayPosition)`
  Setter for debugOverlayPosition.
  `void`
  `setLogAudioRendererEvents(boolean logAudioRendererEvents)`
  Setter for logAudioRendererEvents
  `void`
  `setLogDecoderCounters(boolean logDecoderCounters)`
  Setter for logDecoderCounters
  `void`
  `setLogDownloadCanceled(boolean logDownloadCanceled)`
  Setter for logDownloadCanceled
  `void`
  `setLogDownloadCompleted(boolean logDownloadCompleted)`
  Setter for logDownloadCompleted
  `void`
  `setLogDownloadError(boolean logDownloadError)`
  Setter for logDownloadError
  `void`
  `setLogDownloadStarted(boolean logDownloadStarted)`
  Setter for logDownloadStarted
  `void`
  `setLogDownloadUpstreamDiscarded(boolean logDownloadUpstreamDiscarded)`
  Setter for logDownloadUpstreamDiscarded
  `void`
  `setLogLoadControl(boolean logLoadControl)`
  Setter for logLoadControl
  `void`
  `setLogOpenBundle(boolean logOpenBundle)`
  Setter for logOpenBundle
  `void`
  `setLogPeriodInfo(boolean logPeriodInfo)`
  Setter for logPeriodInfo
  `void`
  `setLogSupportedDrm(boolean logSupportedDrm)`
  Setter for logSupportedDrm
  `void`
  `setLogTimingDebugInfo(boolean logTimingDebugInfo)`
  Log timing info related to playback.
  `void`
  `setLogTransferInfo(boolean logTransferInfo)`
  Setter for logTransferInfo
  `void`
  `setLogVideoFrameMetadata(boolean logVideoFrameMetadata)`
  Setter for logging video frame metadata
  `void`
  `setLogVideoRendererEvents(boolean logVideoRendererEvents)`
  Setter for logVideoRendererEvents
  `void`
  `setRateLimiterEnabled(boolean rateLimiterEnabled)`
  Setter for rateLimiterEnabled

  ### Methods inherited from class com.castlabs.android.Plugin

  `init, onRemotePlay`

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### DEBUG_OVERLAY_ID

    @IdRes public static final int DEBUG_OVERLAY_ID
    The ID of the debug overlay view.

  - ### enableDebugOverlay

    public final boolean enableDebugOverlay
    If true, the debug overlay is enabled.

  - ### initialRateLimitBps

    public final long initialRateLimitBps
    The initial rate limit in bits per second.

  - ### logAVSyncThresholdUs

    public final long logAVSyncThresholdUs
    The threshold in microseconds for logging AV sync values.

  - ### logMeanAndDeviationPeriodUs

    public final long logMeanAndDeviationPeriodUs
    The period in microseconds for logging mean and deviation of AV sync values.

  - ### logRequestTypes

    public final List<Integer> logRequestTypes
    A list of request types to log.

  - ### logResponseTypes

    public final List<Integer> logResponseTypes
    A list of response types to log.

- ## Method Details

  - ### getLogOpenBundle

    public boolean getLogOpenBundle()
    Getter for logOpenBundle
    Returns:
      logOpenBundle

  - ### setLogOpenBundle

    public void setLogOpenBundle(boolean logOpenBundle)
    Setter for logOpenBundle
    Parameters:
      `logOpenBundle` - Sets this value to the property

  - ### getLogDownloadStarted

    public boolean getLogDownloadStarted()
    Getter for logDownloadStarted
    Returns:
      logDownloadStarted

  - ### setLogDownloadStarted

    public void setLogDownloadStarted(boolean logDownloadStarted)
    Setter for logDownloadStarted
    Parameters:
      `logDownloadStarted` - Sets this value to the property

  - ### getLogDownloadCompleted

    public boolean getLogDownloadCompleted()
    Getter for logDownloadCompleted
    Returns:
      logDownloadCompleted

  - ### setLogDownloadCompleted

    public void setLogDownloadCompleted(boolean logDownloadCompleted)
    Setter for logDownloadCompleted
    Parameters:
      `logDownloadCompleted` - Sets this value to the property

  - ### getLogDownloadCanceled

    public boolean getLogDownloadCanceled()
    Getter for logDownloadCanceled
    Returns:
      logDownloadCanceled

  - ### setLogDownloadCanceled

    public void setLogDownloadCanceled(boolean logDownloadCanceled)
    Setter for logDownloadCanceled
    Parameters:
      `logDownloadCanceled` - Sets this value to the property

  - ### getLogDownloadUpstreamDiscarded

    public boolean getLogDownloadUpstreamDiscarded()
    Getter for logDownloadUpstreamDiscarded
    Returns:
      logDownloadUpstreamDiscarded

  - ### setLogDownloadUpstreamDiscarded

    public void setLogDownloadUpstreamDiscarded(boolean logDownloadUpstreamDiscarded)
    Setter for logDownloadUpstreamDiscarded
    Parameters:
      `logDownloadUpstreamDiscarded` - Sets this value to the property

  - ### getLogDownloadError

    public boolean getLogDownloadError()
    Getter for logDownloadError
    Returns:
      logDownloadError

  - ### setLogDownloadError

    public void setLogDownloadError(boolean logDownloadError)
    Setter for logDownloadError
    Parameters:
      `logDownloadError` - Sets this value to the property

  - ### getLogVideoRendererEvents

    public boolean getLogVideoRendererEvents()
    Getter for logVideoRendererEvents
    Returns:
      logVideoRendererEvents

  - ### setLogVideoRendererEvents

    public void setLogVideoRendererEvents(boolean logVideoRendererEvents)
    Setter for logVideoRendererEvents

    Note the value set here will only take effect once the component overlay is created. If you want to change the value at runtime, you need to get an instance of `DebugPlayerControllerComponent` through `getDebugComponent(PlayerController)` and call `DebugPlayerControllerComponent.enableLogVideoRendererEvents()` or `DebugPlayerControllerComponent.disableLogVideoRendererEvents()`.

    Parameters:
      `logVideoRendererEvents` - Sets this value to the property

  - ### getLogAudioRendererEvents

    public boolean getLogAudioRendererEvents()
    Getter for logAudioRendererEvents
    Returns:
      logAudioRendererEvents

  - ### setLogAudioRendererEvents

    public void setLogAudioRendererEvents(boolean logAudioRendererEvents)
    Setter for logAudioRendererEvents

    Note the value set here will only take effect once the component overlay is created. If you want to change the value at runtime, you need to get an instance of `DebugPlayerControllerComponent` through `getDebugComponent(PlayerController)` and call `DebugPlayerControllerComponent.enableLogAudioRendererEvents()` or `DebugPlayerControllerComponent.disableLogAudioRendererEvents()`.

    Parameters:
      `logAudioRendererEvents` - Sets this value to the property

  - ### getLogDecoderCounters

    public boolean getLogDecoderCounters()
    Getter for logDecoderCounters
    Returns:
      logDecoderCounters

  - ### setLogDecoderCounters

    public void setLogDecoderCounters(boolean logDecoderCounters)
    Setter for logDecoderCounters

    Note the value set here will only take effect once the component overlay is created. If you want to change the value at runtime, you need to get an instance of `DebugPlayerControllerComponent` through `getDebugComponent(PlayerController)` and call `DebugPlayerControllerComponent.enableLogDecoderCounters()` or `DebugPlayerControllerComponent.disableLogDecoderCounters()`.

    Parameters:
      `logDecoderCounters` - Sets this value to the property

  - ### getLogTransferInfo

    public boolean getLogTransferInfo()
    Getter for logTransferInfo
    Returns:
      logTransferInfo

  - ### setLogTransferInfo

    public void setLogTransferInfo(boolean logTransferInfo)
    Setter for logTransferInfo

    Note the value set here will only take effect once the component overlay is created. If you want to change the value at runtime, you need to get an instance of `DebugPlayerControllerComponent` through `getDebugComponent(PlayerController)` and call `DebugPlayerControllerComponent.enableLogTransferInfo()` or `DebugPlayerControllerComponent.disableLogTransferInfo()`.

    Parameters:
      `logTransferInfo` - Sets this value to the property

  - ### getLogTimingDebugInfo

    public boolean getLogTimingDebugInfo()
    Getter for logTimingDebugInfo
    Returns:
      whether timing info logging is enabled

  - ### setLogTimingDebugInfo

    public void setLogTimingDebugInfo(boolean logTimingDebugInfo)
    Log timing info related to playback. This is particularly helpful for live streams
    Parameters:
      `logTimingDebugInfo` - set whether to log timing info

  - ### getLogPeriodInfo

    public boolean getLogPeriodInfo()
    Getter for logPeriodInfo
    Returns:
      logPeriodInfo

  - ### setLogPeriodInfo

    public void setLogPeriodInfo(boolean logPeriodInfo)
    Setter for logPeriodInfo

    Note the value set here will only take effect once the component overlay is created. If you want to change the value at runtime, you need to get an instance of `DebugPlayerControllerComponent` through `getDebugComponent(PlayerController)` and call `DebugPlayerControllerComponent.enableLogPeriodInfo()` or `DebugPlayerControllerComponent.disableLogPeriodInfo()`.

    Parameters:
      `logPeriodInfo` - Sets this value to the property

  - ### getLogSupportedDrm

    public boolean getLogSupportedDrm()
    Getter for logSupportedDrm
    Returns:
      logSupportedDrm

  - ### setLogSupportedDrm

    public void setLogSupportedDrm(boolean logSupportedDrm)
    Setter for logSupportedDrm
    Parameters:
      `logSupportedDrm` - Sets this value to the property

  - ### getLogLoadControl

    public boolean getLogLoadControl()
    Getter for logLoadControl
    Returns:
      logLoadControl

  - ### setLogLoadControl

    public void setLogLoadControl(boolean logLoadControl)
    Setter for logLoadControl

    Note the value set here will only take effect once the component overlay is created. If you want to change the value at runtime, you need to get an instance of `DebugPlayerControllerComponent` through `getDebugComponent(PlayerController)` and call `DebugPlayerControllerComponent.enableLogLoadControl()` or `DebugPlayerControllerComponent.disableLogLoadControl()`.

    Parameters:
      `logLoadControl` - Sets this value to the property

  - ### getRateLimiterEnabled

    public boolean getRateLimiterEnabled()
    Getter for rateLimiterEnabled
    Returns:
      rateLimiterEnabled

  - ### setRateLimiterEnabled

    public void setRateLimiterEnabled(boolean rateLimiterEnabled)
    Setter for rateLimiterEnabled
    Parameters:
      `rateLimiterEnabled` - Sets this value to the property

  - ### setLogVideoFrameMetadata

    public void setLogVideoFrameMetadata(boolean logVideoFrameMetadata)
    Setter for logging video frame metadata
    Parameters:
      `logVideoFrameMetadata` - true to enable logging video frame metadata, false otherwise.

  - ### getLogVideoFrameMetadata

    public boolean getLogVideoFrameMetadata()
    Getter for logging video frame metadata
    Returns:
      logVideoFrameMetadata

  - ### getDebugOverlayPosition

    public DebugPlugin.DebugOverlayPosition getDebugOverlayPosition()
    Getter for debugOverlayPosition
    Returns:
      debugOverlayPosition

  - ### setDebugOverlayPosition

    public void setDebugOverlayPosition(DebugPlugin.DebugOverlayPosition debugOverlayPosition)
    Setter for debugOverlayPosition.

    Note the value set here will only take effect when the debug overlay is created. If you want to change the position at runtime, you need to get an instance of `OverlayControllerComponent` through `getOverlayController(PlayerController)` and call `OverlayControllerComponent.setDebugOverlayPosition(DebugOverlayPosition)`.

    Parameters:
      `debugOverlayPosition` - Sets this value to the property

  - ### getId

    @NonNull public String getId()
    Specified by:
      `getId` in class `Plugin`

  - ### getRateLimiter

    @Nullable public RateLimiter getRateLimiter()
    Returns the rate limiter if it was enabled or null
    Returns:
      rate limiter or null

  - ### getVideoCodecAdapterFactory

    @Nullable public DebugMediaCodecAdapterFactory getVideoCodecAdapterFactory()
    Returns the debug media codec adapter factory if it was enabled or null.
    Returns:
      The debug media codec adapter factory or null.

  - ### getDebugComponent

    @Nullable public static DebugPlayerControllerComponent getDebugComponent(@NonNull PlayerController playerController)
    Gets the `DebugPlayerControllerComponent` associated with the given `PlayerController`.

    Example usage:

           DebugPlayerControllerComponent component =
               DebugPlugin.getDebugComponent(playerController);
           if (component != null) {
               component.enableLogPeriodInfo();
           }

    Parameters:
      `playerController` - the controller to query
    Returns:
      the debug component instance or `null` if not available

  - ### getOverlayController

    @Nullable public static OverlayControllerComponent getOverlayController(@NonNull PlayerController playerController)
    Gets the `OverlayControllerComponent` associated with the given `PlayerController`.

    Example usage:

           OverlayControllerComponent overlay =
               DebugPlugin.getOverlayController(playerController);
           if (overlay != null) {
               overlay.enableDebugOverlay();
           }

    Parameters:
      `playerController` - the controller to query
    Returns:
      the overlay controller instance or `null` if not available