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);