HISPlayer SDK UI Customization Guide

This guide explains how to customize the visual appearance and layout of the HISPlayer UI controls to match your brand and application design.

1. UI Layout Customization

You can freely define which buttons and controls appear in the player's bottom control bar, and their exact placement (left, center, or right alignment).

By default, HISPlayer populates the UI based on standard behavior, but you can override this by providing a layout object inside config.ui.

Supported Control Components

You can use the following string identifiers in your layout arrays (see UILayout in the API documentation for the full reference):

• 'volume' - Volume button and slider
• 'time' - Current time and duration label
• 'rewind' - Rewind button
• 'play' - Play/Pause button
• 'forward' - Forward button
• 'loop' - Loop toggle button
• 'playbackRates' - Playback speed selector
• 'quality' - Quality (ABR) levels selector
• 'chapters' - Chapters menu
• 'audios' - Audio tracks menu
• 'subtitles' - Subtitles/CC menu
• 'airplay' - Apple AirPlay button
• 'chromecast' - Google Chromecast button
• 'pip' - Picture-in-Picture button
• 'fullscreen' - Fullscreen toggle button
• 'stereoVR' - Stereo VR button
• 'resetVR' - Reset VR view button
• 'social' - Social Sharing button

Example Layout

const config = {
  // ... other playback configurations
  ui: {
    enabled: true,
    layout: {
      left: ['play', 'volume', 'time'],
      center: ['rewind', 'forward'],
      right: ['quality', 'audios', 'subtitles', 'fullscreen']
    }
  }
};

hisplayer.init(config);

If you don't declare a specific component in the layout arrays, it will simply not be rendered, providing a clean way to hide unwanted controls. Note: If config.ui.layout is undefined, the default logic will be used.

2. UI Styling Customization (Icons & Colors)

You can customize the icon, color, opacity, and other visual properties of each individual button. This is done through the customStyles object inside config.ui.

Each key in config.ui.customStyles corresponds to a component identifier (the same identifiers used in the layout above). For a full list of styling options available per component, refer to the CustomStyles type definition in the API documentation.

Supported Style Variations

For buttons that have multiple states (e.g., Play / Pause, Mute / Unmute), you can define standard CSS properties for each state, or general properties for the whole button.

Example Styles

const config = {
  // ... other playback configurations
  ui: {
    enabled: true,
    customStyles: {
      play: {
        // You can use background image URLs for custom icons
        iconPlay: 'url(https://myapp.com/assets/play-icon.svg)',
        iconPause: 'url(https://myapp.com/assets/pause-icon.svg)',
        iconReplay: 'url(https://myapp.com/assets/replay-icon.svg)',
        opacity: '0.8'
      },
      volume: {
        // Or simply adjust the color of the default SVGs using CSS filters or colors
        color: '#ff0000',
        iconVolumeHigh: 'url(...)',
        iconVolumeMedium: 'url(...)',
        iconVolumeLow: 'url(...)',
        iconMute: 'url(...)',
        slider: {
          color: '#2a5cffff'
        }
      },
      fullscreen: {
        iconEnter: 'url(...)',
        iconExit: 'url(...)'
      },
      time: {
        backgroundColor: '#000000',
        color: '#ffffff',
        fontSize: '14px',
        fontWeight: 'bold'
      }
    }
  }
};

These custom styles are injected into the DOM components as inline styles.

3. Volume Slider Direction

You can configure the volume slider to expand vertically instead of horizontally, which is useful when space is tight or horizontal real estate is occupied by other controls.

const config = {
  ui: {
    options: {
      // 'horizontal' (default) or 'vertical'
      volumeSliderDirection: 'vertical' 
    }
  }
};

When set to 'vertical', hovering or clicking the volume button will expand a vertical range slider upwards, overlapping the video content rather than pushing sibling buttons sideways.

4. Live Indicator

The Live indicator is a badge that is automatically displayed during live playback and hidden during VoD content or when an ad is playing. Clicking the badge seeks the playback to the live edge.

It is configured through two separate keys inside config.ui:

• options.liveIndicator — controls the behavior and position of the badge.
• customStyles.liveIndicator — controls its visual appearance.

Positioning

The position property accepts the following values:

For all absolute-positioned modes you can fine-tune the exact distance from the edge using offsetTop, offsetBottom, offsetLeft and offsetRight (values in pixels).

Note: When config.ui.autoHide is enabled, the live indicator fades in and out together with the rest of the player controls.

Example

const config = {
  // ... other playback configurations
  ui: {
    enabled: true,
    options: {
      liveIndicator: {
        // Show the live indicator badge
        enabled: true,
        // Custom label text (defaults to the localized 'LIVE' string)
        text: 'LIVE',
        // Position of the badge inside the player.
        // 'default' embeds it in the time row; other values use an absolute overlay.
        position: 'top-left', // 'default' | 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
        // Fine-tune the offset from the chosen edge (pixels). Only used for non-'default' positions.
        offsetTop: 12,
        offsetLeft: 12,
      }
    },
    customStyles: {
      liveIndicator: {
        backgroundColor: '#e50000',
        color: '#ffffff',
        fontFamily: 'Inter, sans-serif',
        fontSize: '12px',
        fontWeight: 'bold',
        letterSpacing: '1px',
        textTransform: 'uppercase',
        padding: '4px 10px',
        borderRadius: '4px',
        boxShadow: '0 2px 6px rgba(0,0,0,0.4)',
        // Optional border
        border: '1px solid rgba(255,255,255,0.3)'
      }
    }
  }
};

hisplayer.init(config);

5. Live STT Caption Styling

Live speech-to-text captions are drawn in their own overlay, separate from the classic (manifest) subtitle track. That means you can style them independently: changing their appearance never affects the subtitles embedded in the stream, and vice versa.

Captions are configured through the style object inside config.kollusSTTSubtitles. Every value is a standard CSS value, and an empty string means inherit the player's default caption styling. See SttSubtitlesConfig in the API documentation for the full reference.

Supported Style Options

Example Styles

const config = {
  // ... other playback configurations
  kollusSTTSubtitles: {
    supportedLanguages: ['ko', 'en'],
    language: 'en',
    autoConnect: true,
    style: {
      // Sized in vmin so captions keep scaling with the player and in fullscreen
      fontSize: '3.6vmin',
      fontWeight: 700,
      fontFamily: '"Noto Sans", Arial, sans-serif',
      color: '#ffffff',
      backgroundColor: 'rgba(0, 0, 0, 0.9)',
      // Spacing between the lines currently on screen, and inside a wrapped line
      lineGap: '6px',
      lineHeight: 1.3
    }
  }
};

hisplayer.init(config);

A caption overlay without the background box, relying on a shadow for legibility:

const config = {
  // ... other playback configurations
  kollusSTTSubtitles: {
    supportedLanguages: ['ko', 'en'],
    style: {
      fontSize: '3.6vmin',
      fontWeight: 600,
      color: '#f5f0e6',
      backgroundColor: 'transparent',
      textShadow: '0 2px 4px rgba(0,0,0,0.9), 0 0 2px rgba(0,0,0,0.8)',
      lineGap: '4px'
    }
  }
};

hisplayer.init(config);

Notes

• Sizing and fullscreen. By default captions inherit the player's caption styling, which scales the text up in fullscreen. A fixed length such as '24px' replaces that scaling, so prefer a viewport-relative unit like '3.6vmin' if you want captions to keep growing with the player. Percentages are not recommended: they are resolved against a caption row rather than the inherited font size.
• lineGap vs lineHeight. Live captions keep the most recent lines on screen at once (see rollingCues). lineGap is the space between those lines — lower it to make them read as a single block, raise it to separate them clearly, or use '0px' to have their backgrounds touch. lineHeight only affects a single long caption that wraps.
• When changes apply. Styling is applied to each caption as it arrives, so a new configuration takes effect from the next caption onwards.
• Fonts and language. If you enable a language with a non-Latin script (for example Korean), choose a fontFamily that provides those glyphs.
• Native rendering. style is not used when preferNativeSubtitleRendering is enabled, because captions are then rendered and styled by the browser's own caption settings.

Accessibility

Live captions are announced to screen readers automatically, through a dedicated live region that is updated as the playhead reaches each caption. Two options in config.kollusSTTSubtitles control this:

const config = {
  // ... other playback configurations
  kollusSTTSubtitles: {
    supportedLanguages: ['ko', 'en'],
    announceCaptions: true,
    ariaLabel: 'Live captions'
  }
};

hisplayer.init(config);