# Player Options

`PlayerOption` controls the video player's behavior and appearance. It provides extensive customization for UI elements, playback behavior, and player modes.

## Overview

`PlayerOption` is one of the most comprehensive configuration options, with 30+ properties to customize:

* Player display modes
* UI element visibility and styling
* Autoplay behavior
* Sharing functionality
* Picture-in-Picture mode
* Subtitle and caption controls
* Orientation settings

## Creating PlayerOption

### Using Builder

```kotlin
val playerOption = PlayerOption.Builder()
    .playerMode(PlayerMode.FULL_BLEED_MODE)
    .autoplay(false)
    .showShareButton(true)
    .showMuteButton(true)
    .enablePipMode(true)
    .build()
```

### Using DSL (Recommended)

```kotlin
val viewOptions = viewOptions {
    playerOptions {
        playerMode(PlayerMode.FULL_BLEED_MODE)
        autoplay(false)
        showShareButton(true)
        showMuteButton(true)
        enablePipMode(true)
    }
}
```

## Properties Reference

### Player Display

#### playerMode

**Type:** `PlayerMode` (enum)\
**Default:** `FULL_BLEED_MODE`

Controls how video is scaled and displayed.

**Values:**

* `FULL_BLEED_MODE` - Video fills entire screen, may be cropped
* `FIT_MODE` - Video fits within bounds, may have letterboxing

```kotlin
playerOptions {
    playerMode(PlayerMode.FIT_MODE)
}
```

#### ignoreContentRatioMismatch

**Type:** `Boolean`\
**Default:** `false`

When enabled, the player ignores mismatches between the video content's aspect ratio and the player container's aspect ratio. This prevents the player from applying additional adjustments (such as switching display mode) when the content ratio does not match the expected ratio.

**Behavior:**

* `true` - The player does not react to aspect ratio mismatches; the video is displayed using the configured `playerMode` regardless of its actual ratio
* `false` - The player may adjust rendering based on content aspect ratio differences

```kotlin
playerOptions {
    ignoreContentRatioMismatch(true)
}
```

#### scrollingOrientation

**Type:** `ScrollingOrientation` (enum)\
**Default:** `HORIZONTAL`

Direction for swiping between videos in the player.

**Values:**

* `HORIZONTAL` - Swipe left/right
* `VERTICAL` - Swipe up/down

```kotlin
playerOptions {
    scrollingOrientation(ScrollingOrientation.VERTICAL)
}
```

#### enableRotateOrientation

**Type:** `Boolean`\
**Default:** `false`

Enable or disable device orientation rotation for the player. When enabled, users can rotate their device to switch between portrait and landscape modes while watching videos.

**Behavior:**

* `true` - Player allows device orientation changes (`SCREEN_ORIENTATION_USER`). The player will rotate based on the device's physical orientation.
* `false` - Player is locked to portrait mode (`SCREEN_ORIENTATION_PORTRAIT`). The player will not rotate regardless of device orientation.

```kotlin
playerOptions {
    enableRotateOrientation(true)
}
```

**Example: Enable landscape mode for video playback**

```kotlin
val viewOptions = viewOptions {
    playerOptions {
        enableRotateOrientation(true)  // Allow user to rotate device
    }
}

// Apply to VideoFeedView
videoFeedView.init(viewOptions = viewOptions)
```

**Note:** This setting affects the entire `PlayerActivity`. When the user rotates the device and `enableRotateOrientation` is enabled, the player UI will automatically adapt to the new orientation.

### UI Element Visibility

#### showFireworkLogo

**Type:** `Boolean`\
**Default:** `true`

Show or hide the Firework logo in the player.

```kotlin
playerOptions {
    showFireworkLogo(false)
}
```

#### logoConfig

**Type:** `LogoConfig`\
**Default:** `LogoConfig.NoLogo`

Configure custom logo display in the player.

**Values:**

* `NoLogo` - No logo shown
* `Logo.AggregatorLogo(channelId, isClickable)` - Custom drawable logo from channel
* `Logo.CreatorLogo(channelId, isClickable)` - Custom drawable logo from creator

```kotlin
playerOptions {
    logoConfig(
        LogoConfig.CreatorLogo(
            channelId = "encoded_channel_id",
            isClickable = true
        )
    )
}
```

#### showShareButton

**Type:** `Boolean`\
**Default:** `true`

Show or hide the share button.

```kotlin
playerOptions {
    showShareButton(true)
}
```

#### showMuteButton

**Type:** `Boolean`\
**Default:** `true`

Show or hide the mute/unmute button.

```kotlin
playerOptions {
    showMuteButton(true)
}
```

#### showPlayPauseButtonInVideo

**Type:** `Boolean`\
**Default:** `true`

Show or hide play/pause button for regular videos.

```kotlin
playerOptions {
    showPlayPauseButtonInVideo(true)
}
```

#### showPlayPauseButtonInReplay

**Type:** `Boolean`\
**Default:** `true`

Show or hide play/pause button for livestream replays.

```kotlin
playerOptions {
    showPlayPauseButtonInReplay(true)
}
```

#### showMoreButton

**Type:** `Boolean`\
**Default:** `true`

Show or hide the more options button.

```kotlin
playerOptions {
    showMoreButton(true)
}
```

#### **showProductCard**

**Type:** `Boolean`

**Default:** `true`

Show or hide product cards in shoppable videos. When enabled and the video has associated products, product cards will be displayed in the player.

**Behavior:**

* `true` - Product cards are visible when the video has associated products
* `false` - Product cards are hidden regardless of whether products are available

```kotlin
playerOptions {
    showProductCard(true)
}
```

**Use Cases:**

* Control product visibility in shoppable video experiences
* Hide products when focusing on video content only
* A/B testing product card display

**Note:** This setting only affects videos that have products associated with them. For videos without products, this setting has no visible effect.

#### isArrowButtonVisible

**Type:** `Boolean`\
**Default:** `true`

Show or hide the arrow buttons used to navigate between videos in the fullscreen player. When visible, users can tap the left/right arrow buttons to switch to the previous or next video without swiping.

**Applies to:** Fullscreen player (`PlayerActivity`). For the arrow button in `FwStoryBlockView`, see [StoryBlockOption.isArrowButtonVisible](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/story-block-options#isarrowbuttonvisible).

```kotlin
playerOptions {
    isArrowButtonVisible(false)
}
```

**Behavior:**

* `true` - Arrow navigation buttons are visible in the fullscreen player
* `false` - Arrow buttons are hidden; users must swipe to navigate between videos

### Playback Behavior

#### autoplay

**Type:** `Boolean`\
**Default:** `false`

Auto-play videos on FwVideoFeedView layout for first element.

```kotlin
playerOptions {
    autoplay(true)
}
```

#### autoPlayOnComplete

**Type:** `Boolean`\
**Default:** `true`

Automatically play next video when current video ends.

```kotlin
playerOptions {
    autoPlayOnComplete(true)
}
```

#### feedCompleteAction

**Type:** `FeedCompleteAction` (enum)\
**Default:** `DISMISS`

Controls the behavior when all videos in the feed have finished playing.

**Values:**

* `LOOP` - Restart playback from the first video in the feed
* `DISMISS` - Close the player when all videos have been played

```kotlin
playerOptions {
    feedCompleteAction(FeedCompleteAction.LOOP)
}
```

**Use Cases:**

* Use `LOOP` for kiosk displays or continuous playback scenarios
* Use `DISMISS` (default) for standard user experiences where the player closes after all content is consumed

### Sharing

#### shareBaseUrl

**Type:** `String?`\
**Default:** Empty string

Base URL for generating share links.

```kotlin
playerOptions {
    shareBaseUrl("https://your-app.com/videos")
}
```

#### shareUrlCustomCallBack

**Type:** `suspend (url: String, videoInfo: VideoInfo) -> String`\
**Default:** Returns original URL

Custom callback to modify share URLs before sharing.

```kotlin
playerOptions {
    shareUrlCustomCallBack { url, videoInfo ->
        // Modify URL with custom parameters
        "$url?utm_source=app&video_id=${videoInfo.videoId}"
    }
}
```

#### shareButtonPosition

**Type:** `ShareButtonPosition` (enum)\
**Default:** `MORE_MENU`

Controls where the share button is displayed in the player UI.

**Values:**

* `MORE_MENU` - Share button appears inside the more options (⋯) menu
* `MAIN_VIDEO_VIEW` - Share button is displayed directly on the main video view as a standalone button

```kotlin
playerOptions {
    shareButtonPosition(ShareButtonPosition.MAIN_VIDEO_VIEW)
}
```

**Note:** This option only takes effect when `showShareButton` is `true`.

### CTA Handling

#### sdkHandleCtaButtonClick

**Type:** `Boolean`\
**Default:** `true`

Whether SDK handles CTA button clicks automatically.

```kotlin
playerOptions {
    sdkHandleCtaButtonClick(false) // Handle CTA clicks in your app
}
```

### Picture-in-Picture

#### enablePipMode

**Type:** `Boolean`\
**Default:** `false`

Enable Picture-in-Picture mode.

```kotlin
playerOptions {
    enablePipMode(true)
}
```

### Subtitles and Captions

#### showSubtitle

**Type:** `Boolean`\
**Default:** `true`

Show or hide video subtitles.

```kotlin
playerOptions {
    showSubtitle(true)
}
```

#### showCaption

**Type:** `Boolean`\
**Default:** `true`

Show or hide video captions.

```kotlin
playerOptions {
    showCaption(true)
}
```

#### subtitleTextColor

**Type:** `Int` (color)\
**Default:** White (`0xFFFFFFFF`)

Text color for subtitles.

```kotlin
playerOptions {
    subtitleTextColor(Color.WHITE)
}
```

#### subtitleBackgroundColor

**Type:** `Int` (color)\
**Default:** Semi-transparent black (`0x66121212`)

Background color for subtitles.

```kotlin
playerOptions {
    subtitleBackgroundColor(Color.parseColor("#80000000"))
}
```

### Livestream

#### livestreamCountDownOption

**Type:** `LivestreamCountDownOption`\
**Default:** Default configuration

Configure livestream countdown UI style.

```kotlin
playerOptions {
    livestreamCountDownOption(
        LivestreamCountDownOption.Builder()
            .isHidden(true)
            .theme(Theme.Dark)
            .build()
    )
}
```

### Immersive Mode

#### enableImmersiveMode

**Type:** `Boolean`\
**Default:** `false`

Enable immersive fullscreen mode (hide system UI).

```kotlin
playerOptions {
    enableImmersiveMode(true)
}
```

### Advanced UI Configuration

#### playerUiOption

**Type:** `PlayerUiOption`\
**Default:** Default configuration

Advanced configuration for player UI elements including custom icons and detailed options. This allows you to customize individual player controls with custom icons and behaviors.

```kotlin
playerOptions {
    playerUiOption(
        PlayerUiOption.Builder()
            .videoDetailsOption(
                VideoDetailsOption.Builder()
                    .buttonIcon(WidgetImage(R.drawable.ic_info, Color.WHITE))
                    .showCaption(true)
                    .build()
            )
            .closeButtonOption(
                CloseButtonOption.Builder()
                    .icon(WidgetImage(R.drawable.ic_close))
                    .shouldShowWhenPiPEnabled(false)
                    .build()
            )
            .pipButtonOption(
                PipButtonOption.Builder()
                    .icon(WidgetImage(R.drawable.ic_pip))
                    .build()
            )
            .muteButtonOption(
                MuteButtonOption.Builder()
                    .muteIcon(WidgetImage(R.drawable.ic_mute))
                    .unmuteIcon(WidgetImage(R.drawable.ic_unmute))
                    .build()
            )
            .playbackButtonOption(
                PlaybackButtonOption.Builder()
                    .playIcon(WidgetImage(R.drawable.ic_play))
                    .pauseIcon(WidgetImage(R.drawable.ic_pause))
                    .build()
            )
            .build()
    )
}
```

**PlayerUiOption Properties**

| Property               | Type                   | Description                                 |
| ---------------------- | ---------------------- | ------------------------------------------- |
| `videoDetailsOption`   | `VideoDetailsOption`   | Configuration for video details button      |
| `closeButtonOption`    | `CloseButtonOption`    | Configuration for close button              |
| `pipButtonOption`      | `PipButtonOption`      | Configuration for Picture-in-Picture button |
| `muteButtonOption`     | `MuteButtonOption`     | Configuration for mute/unmute button        |
| `playbackButtonOption` | `PlaybackButtonOption` | Configuration for play/pause button         |

***

#### VideoDetailsOption

Configuration for the video details button in the player.

```kotlin
VideoDetailsOption.Builder()
    .buttonIcon(WidgetImage(R.drawable.ic_info, Color.WHITE))
    .showCaption(true)
    .build()
```

| Property      | Type           | Default | Description                              |
| ------------- | -------------- | ------- | ---------------------------------------- |
| `buttonIcon`  | `WidgetImage?` | `null`  | Custom icon for the video details button |
| `showCaption` | `Boolean`      | `true`  | Whether to show video caption            |

***

#### CloseButtonOption

Configuration for the close button in the player.

```kotlin
CloseButtonOption.Builder()
    .icon(WidgetImage(R.drawable.ic_close))
    .shouldShowWhenPiPEnabled(false)
    .build()
```

| Property                   | Type           | Default | Description                                           |
| -------------------------- | -------------- | ------- | ----------------------------------------------------- |
| `icon`                     | `WidgetImage?` | `null`  | Custom icon for the close button                      |
| `shouldShowWhenPiPEnabled` | `Boolean`      | `false` | Whether to show close button when PiP mode is enabled |

***

#### PipButtonOption

Configuration for the Picture-in-Picture button in the player.

```kotlin
PipButtonOption.Builder()
    .icon(WidgetImage(R.drawable.ic_pip))
    .build()
```

| Property | Type           | Default | Description                    |
| -------- | -------------- | ------- | ------------------------------ |
| `icon`   | `WidgetImage?` | `null`  | Custom icon for the PiP button |

***

#### MuteButtonOption

Configuration for the mute/unmute button in the player.

```kotlin
MuteButtonOption.Builder()
    .muteIcon(WidgetImage(R.drawable.ic_mute))
    .unmuteIcon(WidgetImage(R.drawable.ic_unmute))
    .build()
```

| Property     | Type           | Default | Description                   |
| ------------ | -------------- | ------- | ----------------------------- |
| `muteIcon`   | `WidgetImage?` | `null`  | Custom icon for muted state   |
| `unmuteIcon` | `WidgetImage?` | `null`  | Custom icon for unmuted state |

***

#### PlaybackButtonOption

Configuration for the play/pause button in the player.

```kotlin
PlaybackButtonOption.Builder()
    .playIcon(WidgetImage(R.drawable.ic_play))
    .pauseIcon(WidgetImage(R.drawable.ic_pause))
    .build()
```

| Property    | Type           | Default | Description                 |
| ----------- | -------------- | ------- | --------------------------- |
| `playIcon`  | `WidgetImage?` | `null`  | Custom icon for play state  |
| `pauseIcon` | `WidgetImage?` | `null`  | Custom icon for pause state |

***

#### actionButtonOption

**Type:** `ActionButtonOption`\
**Default:** Default configuration

Configure custom action buttons in the player. This allows you to style the action and cancel buttons with custom colors and shapes.

```kotlin
playerOptions {
    actionButtonOption(
        ActionButtonOption.Builder()
            .actionButton(
                ActionButton(
                    backgroundColor = Color.parseColor("#FF5722"),
                    textColor = Color.WHITE,
                    shape = Shape.SHAPE_ROUND_RECTANGLE,
                    dividingLineColor = Color.GRAY
                )
            )
            .cancelButton(
                ActionButton(
                    backgroundColor = Color.TRANSPARENT,
                    textColor = Color.WHITE,
                    shape = Shape.SHAPE_OVAL
                )
            )
            .build()
    )
}
```

**ActionButtonOption Properties**

| Property       | Type            | Description                                 |
| -------------- | --------------- | ------------------------------------------- |
| `actionButton` | `ActionButton?` | Configuration for the primary action button |
| `cancelButton` | `ActionButton?` | Configuration for the cancel button         |

***

#### ActionButton

Styling configuration for an action button.

| Property            | Type     | Default | Description                    |
| ------------------- | -------- | ------- | ------------------------------ |
| `backgroundColor`   | `Int?`   | `null`  | Background color of the button |
| `textColor`         | `Int?`   | `null`  | Text color of the button       |
| `shape`             | `Shape?` | `null`  | Shape of the button            |
| `dividingLineColor` | `Int?`   | `null`  | Color of the dividing line     |

**Shape Values:**

* `SHAPE_ROUND_RECTANGLE` - Rounded rectangle shape
* `SHAPE_OVAL` - Oval/circular shape

***

#### WidgetImage

Custom image configuration for player UI elements.

```kotlin
WidgetImage(
    drawableRes = R.drawable.ic_custom_icon,
    tintColor = Color.WHITE  // Optional
)
```

| Property      | Type   | Default  | Description                           |
| ------------- | ------ | -------- | ------------------------------------- |
| `drawableRes` | `Int`  | Required | Drawable resource ID (`@DrawableRes`) |
| `tintColor`   | `Int?` | `null`   | Optional tint color (`@ColorInt`)     |

***

#### LivestreamCountDownOption

Configuration for livestream countdown UI.

```kotlin
LivestreamCountDownOption.Builder()
    .isHidden(false)
    .theme(Theme.DARK)
    .build()
```

| Property   | Type      | Default | Description                   |
| ---------- | --------- | ------- | ----------------------------- |
| `isHidden` | `Boolean` | `true`  | Whether to hide the countdown |
| `theme`    | `Theme`   | `DARK`  | Theme for the countdown UI    |

**Theme Values:**

* `LIGHT` - Light theme
* `DARK` - Dark theme

## Default Values

### Player Options

| Property                      | Default Value                         |
| ----------------------------- | ------------------------------------- |
| `playerMode`                  | `FULL_BLEED_MODE`                     |
| `scrollingOrientation`        | `HORIZONTAL`                          |
| `ignoreContentRatioMismatch`  | `false`                               |
| `showFireworkLogo`            | `true`                                |
| `showShareButton`             | `true`                                |
| `showMuteButton`              | `true`                                |
| `isArrowButtonVisible`        | `true`                                |
| `autoplay`                    | `false`                               |
| `autoPlayOnComplete`          | `true`                                |
| `feedCompleteAction`          | `DISMISS`                             |
| `enablePipMode`               | `false`                               |
| `showSubtitle`                | `true`                                |
| `showCaption`                 | `true`                                |
| `showMoreButton`              | `true`                                |
| `showProductCard`             | `true`                                |
| `reverseAudioControls`        | `false`                               |
| `enableRotateOrientation`     | `false`                               |
| `tapToEnterLiveStreamHidden`  | `false`                               |
| `enableImmersiveMode`         | `false`                               |
| `sdkHandleCtaButtonClick`     | `true`                                |
| `showPlayPauseButtonInVideo`  | `true`                                |
| `showPlayPauseButtonInReplay` | `true`                                |
| `shareBaseUrl`                | `""`                                  |
| `shareButtonPosition`         | `MORE_MENU`                           |
| `subtitleTextColor`           | `0xFFFFFFFF` (white)                  |
| `subtitleBackgroundColor`     | `0x66121212` (semi-transparent black) |

### UI Option Defaults

| Option Class                | Property                   | Default Value             |
| --------------------------- | -------------------------- | ------------------------- |
| `VideoDetailsOption`        | `buttonIcon`               | `null` (uses SDK default) |
| `VideoDetailsOption`        | `showCaption`              | `true`                    |
| `CloseButtonOption`         | `icon`                     | `null` (uses SDK default) |
| `CloseButtonOption`         | `shouldShowWhenPiPEnabled` | `false`                   |
| `PipButtonOption`           | `icon`                     | `null` (uses SDK default) |
| `MuteButtonOption`          | `muteIcon`                 | `null` (uses SDK default) |
| `MuteButtonOption`          | `unmuteIcon`               | `null` (uses SDK default) |
| `PlaybackButtonOption`      | `playIcon`                 | `null` (uses SDK default) |
| `PlaybackButtonOption`      | `pauseIcon`                | `null` (uses SDK default) |
| `LivestreamCountDownOption` | `isHidden`                 | `true`                    |
| `LivestreamCountDownOption` | `theme`                    | `DARK`                    |

## Important Notes

* `playerMode` affects how videos are displayed: `FULL_BLEED_MODE` fills the screen, `FIT_MODE` fits within bounds
* PIP mode requires `enablePipMode = true` and proper AndroidManifest configuration
* Subtitle colors use Android color integers (`Color.parseColor()` or `Color.*`)
* Share URL callback is suspending - can perform async operations
* Logo configuration overrides `showFireworkLogo` when set
* Immersive mode hides system navigation bars
* Some options (like livestream countdown) require livestream content
* CTA handling affects shopping integration
* `WidgetImage` allows custom icons with optional tint colors - use `@DrawableRes` for drawable resources
* When `icon` properties are `null`, the SDK uses its default built-in icons
* `ActionButton` styling affects CTA buttons in videos - all properties are optional
* `CloseButtonOption.shouldShowWhenPiPEnabled` determines if close button remains visible when entering PiP mode

## See Also

* [ViewOptions Overview](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/configuration) - Complete configuration system
* [BaseOption](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/configuration/base-options) - Content source
* [Shopping Integration](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/shoppable-videos) - CTA handling