tessl/npm-react-h5-audio-player

A customizable React audio player component with TypeScript support, mobile compatibility, and comprehensive accessibility features

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

UI Customization & Layout

Name: tessl/npm-react-h5-audio-player
Author: tessl

Advanced customization system for modifying the player's appearance, layout, and individual UI components through custom icons, layouts, and modular UI sections.

Required Imports

import AudioPlayer, { RHAP_UI } from 'react-h5-audio-player';
import { ReactNode, ReactElement } from 'react';

Capabilities

Layout Configuration

Control the overall arrangement and orientation of player components.

type MAIN_LAYOUT = 'stacked' | 'stacked-reverse' | 'horizontal' | 'horizontal-reverse';

Layout Options:

'stacked' (default): Progress bar above controls
'stacked-reverse': Controls above progress bar
'horizontal': Progress bar and controls side by side
'horizontal-reverse': Controls and progress bar side by side (reversed order)

Custom Icons

Replace default icons with custom React components or elements.

interface CustomIcons {
  /** Custom play button icon */
  play?: ReactNode;
  /** Custom pause button icon */
  pause?: ReactNode;
  /** Custom rewind button icon */
  rewind?: ReactNode;
  /** Custom forward button icon */
  forward?: ReactNode;
  /** Custom previous track button icon */
  previous?: ReactNode;
  /** Custom next track button icon */
  next?: ReactNode;
  /** Custom loop enabled icon */
  loop?: ReactNode;
  /** Custom loop disabled icon */
  loopOff?: ReactNode;
  /** Custom volume button icon */
  volume?: ReactNode;
  /** Custom mute button icon */
  volumeMute?: ReactNode;
}

UI Module System

The player uses a modular UI system where individual components can be customized or rearranged.

enum RHAP_UI {
  CURRENT_TIME = 'CURRENT_TIME',
  CURRENT_LEFT_TIME = 'CURRENT_LEFT_TIME', 
  PROGRESS_BAR = 'PROGRESS_BAR',
  DURATION = 'DURATION',
  ADDITIONAL_CONTROLS = 'ADDITIONAL_CONTROLS',
  MAIN_CONTROLS = 'MAIN_CONTROLS',
  VOLUME_CONTROLS = 'VOLUME_CONTROLS',
  LOOP = 'LOOP',
  VOLUME = 'VOLUME'
}

type CustomUIModule = RHAP_UI | ReactElement;
type CustomUIModules = Array<CustomUIModule>;

Custom UI Sections

Customize the arrangement of UI components in different sections of the player.

interface CustomUISections {
  /** Customize the progress bar section layout */
  customProgressBarSection?: CustomUIModules;
  /** Customize the main controls section layout */
  customControlsSection?: CustomUIModules;
  /** Customize additional controls (like loop button) */
  customAdditionalControls?: CustomUIModules;
  /** Customize volume controls section */
  customVolumeControls?: CustomUIModules;
}

Default Configurations:

customProgressBarSection: [RHAP_UI.CURRENT_TIME, RHAP_UI.PROGRESS_BAR, RHAP_UI.DURATION]
customControlsSection: [RHAP_UI.ADDITIONAL_CONTROLS, RHAP_UI.MAIN_CONTROLS, RHAP_UI.VOLUME_CONTROLS]
customAdditionalControls: [RHAP_UI.LOOP]
customVolumeControls: [RHAP_UI.VOLUME]

Time Display Configuration

Control how time values are formatted and displayed.

type TIME_FORMAT = 'auto' | 'mm:ss' | 'hh:mm:ss';

Time Format Options:

'auto': Automatically choose mm:ss or hh:mm:ss based on duration
'mm:ss': Always use minutes:seconds format
'hh:mm:ss': Always use hours:minutes:seconds format

Internationalization Support

Customize accessibility labels for screen readers and internationalization.

interface I18nAriaLabels {
  /** Main player container label */
  player?: string;
  /** Progress bar control label */
  progressControl?: string;
  /** Volume control label */
  volumeControl?: string;
  /** Play button label */
  play?: string;
  /** Pause button label */
  pause?: string;
  /** Rewind button label */
  rewind?: string;
  /** Forward button label */
  forward?: string;
  /** Previous track button label */
  previous?: string;
  /** Next track button label */
  next?: string;
  /** Loop enabled button label */
  loop?: string;
  /** Loop disabled button label */
  loopOff?: string;
  /** Volume button label */
  volume?: string;
  /** Mute button label */
  volumeMute?: string;
}

Default English Labels:

const defaultI18nAriaLabels: I18nAriaLabels = {
  player: 'Audio player',
  progressControl: 'Audio progress control',
  volumeControl: 'Volume control',
  play: 'Play',
  pause: 'Pause',
  rewind: 'Rewind',
  forward: 'Forward',
  previous: 'Previous',
  next: 'Skip',
  loop: 'Disable loop',
  loopOff: 'Enable loop',
  volume: 'Mute',
  volumeMute: 'Unmute'
};

Usage Examples

Custom Layout Configuration:

<AudioPlayer
  src="audio.mp3"
  layout="horizontal"
  timeFormat="hh:mm:ss"
  showJumpControls={true}
  showSkipControls={true}
/>

Custom Icons:

import { FaPlay, FaPause, FaStepForward, FaStepBackward } from 'react-icons/fa';

<AudioPlayer
  src="audio.mp3"
  customIcons={{
    play: <FaPlay />,
    pause: <FaPause />,
    previous: <FaStepBackward />,
    next: <FaStepForward />
  }}
/>

Custom UI Section Layout:

<AudioPlayer
  src="audio.mp3"
  customProgressBarSection={[
    RHAP_UI.CURRENT_LEFT_TIME,  // Show remaining time instead
    RHAP_UI.PROGRESS_BAR,
    RHAP_UI.DURATION
  ]}
  customControlsSection={[
    RHAP_UI.VOLUME_CONTROLS,    // Volume controls on left
    RHAP_UI.MAIN_CONTROLS,      // Play/pause in center
    RHAP_UI.ADDITIONAL_CONTROLS // Loop on right
  ]}
/>

Custom Components in UI:

const CustomTrackInfo = () => (
  <div className="track-info">
    <span>Track 1 of 10</span>
  </div>
);

<AudioPlayer
  src="audio.mp3"
  customAdditionalControls={[
    <CustomTrackInfo key="track-info" />,
    RHAP_UI.LOOP
  ]}
/>

Internationalization:

<AudioPlayer
  src="audio.mp3"
  i18nAriaLabels={{
    player: 'Lecteur audio',
    play: 'Jouer',
    pause: 'Pause',
    rewind: 'Retour rapide',
    forward: 'Avance rapide',
    volume: 'Muet',
    volumeMute: 'Activer le son'
  }}
/>

Minimal Player (Progress Only):

<AudioPlayer
  src="audio.mp3"
  customProgressBarSection={[RHAP_UI.PROGRESS_BAR]}
  customControlsSection={[]}
  showJumpControls={false}
/>

Full-Featured Player:

<AudioPlayer
  src="audio.mp3"
  layout="horizontal"
  showSkipControls={true}
  showJumpControls={true}
  showFilledProgress={true}
  showFilledVolume={true}
  timeFormat="auto"
  header={<h3>Now Playing: Song Title</h3>}
  footer={<p>Artist Name - Album Name</p>}
  customIcons={{
    play: <CustomPlayIcon />,
    pause: <CustomPauseIcon />
  }}
  customAdditionalControls={[
    <CustomRatingWidget key="rating" />,
    RHAP_UI.LOOP,
    <CustomShareButton key="share" />
  ]}
/>

Styling and CSS Classes:

The player adds various CSS classes for styling:

/* Main container classes */
.rhap_container { /* Main player container */ }
.rhap_stacked { /* Stacked layout */ }
.rhap_horizontal { /* Horizontal layout */ }
.rhap_play-status--playing { /* When playing */ }
.rhap_play-status--paused { /* When paused */ }
.rhap_loop--on { /* When loop is enabled */ }
.rhap_loop--off { /* When loop is disabled */ }

/* Component classes */
.rhap_progress-section { /* Progress bar section */ }
.rhap_controls-section { /* Controls section */ }
.rhap_main-controls { /* Play/pause/skip buttons */ }
.rhap_volume-controls { /* Volume controls */ }
.rhap_additional-controls { /* Additional controls like loop */ }

Custom styling can be applied by importing your own CSS after the default styles:

import 'react-h5-audio-player/lib/styles.css';
import './custom-player-styles.css'; // Your custom styles

Install with Tessl CLI

npx tessl i tessl/npm-react-h5-audio-player

docs

advanced-features-mse.md

component-props-events.md

index.md

ui-customization-layout.md

tile.json

tessl/npm-react-h5-audio-player