useMediaControls

that provides controls for HTML media elements (audio/video)

browser

test coverage

Last changed: 3 days ago

Installation

Library

CLI

Manual

import { useMediaControls } from '@siberiacancode/reactuse';

Usage

const { playing, play, pause } = useMediaControls(videoRef, 'video.mp4');
// or
const { playing, play, pause } = useMediaControls(audioRef, { src: 'audio.mp3', type: 'audio/mp3' });
// or
const { ref, playing, play, pause } = useMediaControls<HTMLVideoElement>('video.mp4');
// or
const { ref, playing, play, pause } = useMediaControls<HTMLVideoElement>({ src: 'video.mp4', type: 'video/mp4' });

Demo

source

Api

Parameters

Name	Type	Default	Note
target	HookTarget	-	The target media element
src	string	-	The source URL of the media

Returns

UseMediaControlsReturn

Parameters

Name	Type	Default	Note
target	HookTarget	-	The target media element
options	UseMediaSource	-	The media source configuration

Returns

UseMediaControlsReturn

Parameters

Name	Type	Default	Note
src	string	-	The source URL of the media

Returns

UseMediaControlsReturn & { ref: StateRef<Target> }

Parameters

Name	Type	Default	Note
options	UseMediaSource	-	The media source configuration

Returns

UseMediaControlsReturn & { ref: StateRef<Target> }

Type declaration

import type { HookTarget } from '@/utils/helpers';

import type { StateRef } from '../useRefState/useRefState';

export interface UseMediaSource {
  /** The media attribute of the media */
  media?: string;
  /** The source URL of the media */
  src: string;
  /** The MIME type of the media */
  type?: string;
}

export interface UseMediaControlsReturn {
  /** Whether the media is currently buffering */
  buffered: [number, number][];
  /** The current playback position in seconds */
  currentTime: number;
  /** The total duration of the media in seconds */
  duration: number;
  /** Whether the media has ended */
  ended: boolean;
  /** Whether the media is currently muted */
  muted: boolean;
  /** The current playback rate (1.0 is normal speed) */
  playbackRate: number;
  /** Whether the media is currently playing */
  playing: boolean;
  /** Whether the media is currently seeking */
  seeking: boolean;
  /** Whether the media is currently stalled */
  stalled: boolean;
  /** The current volume level (0.0 to 1.0) */
  volume: number;
  /** Whether the media is currently waiting */
  waiting: boolean;

  /** Set the playback rate */
  changePlaybackRate: (rate: number) => void;
  /** Set the volume level (0.0 to 1.0) */
  changeVolume: (volume: number) => void;
  /** Set the muted state */
  mute: () => void;
  /** Pause the media */
  pause: () => void;
  /** Start playing the media */
  play: () => Promise<void>;
  /** Seek to a specific time in seconds */
  seek: (time: number) => void;
  /** Toggle between play and pause */
  toggle: () => Promise<void>;
  /** Set the unmuted state */
  unmute: () => void;
}

export interface UseMediaControls {
  (target: HookTarget, src: string): UseMediaControlsReturn;

  (target: HookTarget, options: UseMediaSource): UseMediaControlsReturn;

  <Target extends HTMLMediaElement>(
    src: string
  ): UseMediaControlsReturn & {
    ref: StateRef<Target>;
  };

  <Target extends HTMLMediaElement>(
    options: UseMediaSource
  ): UseMediaControlsReturn & { ref: StateRef<Target> };
}

Source

Source • Demo

Contributors

D

debabin