{"id":13880849,"url":"https://github.com/lhz516/react-h5-audio-player","last_synced_at":"2025-05-14T04:09:17.486Z","repository":{"id":38472999,"uuid":"75695575","full_name":"lhz516/react-h5-audio-player","owner":"lhz516","description":"React audio player component with UI. It provides time indicator on both desktop and mobile devices.","archived":false,"fork":false,"pushed_at":"2024-12-30T07:55:02.000Z","size":8870,"stargazers_count":655,"open_issues_count":26,"forks_count":99,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-13T01:34:02.592Z","etag":null,"topics":["audio","audio-player","music-player","react","react-audio-player","typescript"],"latest_commit_sha":null,"homepage":"https://codepen.io/lhz516/pen/dyGpmgP","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lhz516.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["lhz516"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2016-12-06T04:49:19.000Z","updated_at":"2025-05-08T07:07:01.000Z","dependencies_parsed_at":"2024-06-18T12:30:53.607Z","dependency_job_id":"c9ef1a9b-c7bb-4fba-84b9-d2b639dd3878","html_url":"https://github.com/lhz516/react-h5-audio-player","commit_stats":{"total_commits":176,"total_committers":15,"mean_commits":"11.733333333333333","dds":0.4545454545454546,"last_synced_commit":"78b417c0ed00caa97f9e48c5b1463609f6c56051"},"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lhz516%2Freact-h5-audio-player","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lhz516%2Freact-h5-audio-player/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lhz516%2Freact-h5-audio-player/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lhz516%2Freact-h5-audio-player/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lhz516","download_url":"https://codeload.github.com/lhz516/react-h5-audio-player/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254070037,"owners_count":22009559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","audio-player","music-player","react","react-audio-player","typescript"],"created_at":"2024-08-06T08:03:32.703Z","updated_at":"2025-05-14T04:09:12.471Z","avatar_url":"https://github.com/lhz516.png","language":"TypeScript","funding_links":["https://github.com/sponsors/lhz516"],"categories":["HarmonyOS","JavaScript"],"sub_categories":["Windows Manager"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"logo\" src=\"./assets/logo.png\" width=\"100\" max-width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eReact H5 Audio Player\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/react-h5-audio-player\" title=\"MIT License\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/l/react-h5-audio-player.svg?color=brightgreen\" alt=\"MIT License\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/react-h5-audio-player\" title=\"Monthly download\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dm/react-h5-audio-player.svg?color=green\" alt=\"Monthly download\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/react-h5-audio-player\" title=\"Latest version\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/react-h5-audio-player.svg\" alt=\"Latest version\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n* Audio player component that provides consistent UI/UX on different browsers.\n* Super customizable layout\n* Flexbox css with SVG icons. Mobile friendly.\n* I18n and a11y supported, keyboards events supported.\n* Support Media Source Extensions (MSE) and Encrypted Media Extensions (EME)\n* Written in TypeScript.\n\n![screenshot](./assets/screenshot.png)\n\nLive Demo: [Storybook](https://lhz516.github.io/react-h5-audio-player/)\n\nTry it on CodePen: [Basic](https://codepen.io/lhz516/pen/dyGpmgP), [Playlist](https://codepen.io/lhz516/pen/ZExvXjx)\n\nSupported browsers: Chrome, Firefox, Safari, Edge\n\n## [Migrate from v2.x to v3](https://github.com/lhz516/react-h5-audio-player/releases/tag/v3.0.0)\n\n## Installation\n\n`$ npm i react-h5-audio-player`\n\nOr\n\n`$ yarn add react-h5-audio-player`\n\n## Usage\n\n```jsx\nimport AudioPlayer from 'react-h5-audio-player';\nimport 'react-h5-audio-player/lib/styles.css';\n// import 'react-h5-audio-player/lib/styles.less' Use LESS\n// import 'react-h5-audio-player/src/styles.scss' Use SASS\n\nconst Player = () =\u003e (\n  \u003cAudioPlayer\n    autoPlay\n    src=\"http://example.com/audio.mp3\"\n    onPlay={e =\u003e console.log(\"onPlay\")}\n    // other props here\n  /\u003e\n);\n```\n\n#### Keyboard shortcuts (When audio player focused)\n\nThey can be turned off by setting `hasDefaultKeyBindings` prop to `false`\n\n| Key binding | Action |\n| ----------- | ------ |\n| Space       | Play/Pause |\n| ←           | Rewind |\n| →           | Forward |\n| ↑           | Volume up |\n| ↓           | Volume down |\n| L           | Toggle loop |\n| M           | Toggle mute |\n\n## Props\n\n### HTML Audio Tag Native Attributes\n\n| Props       |  Type                          |  Default  | Note |\n| ----------- | ------------------------------ | --------- | ---- |\n| src         | string                         | ''        | |\n| preload     | 'auto' \\| 'metadata' \\| 'none' | 'auto'    | |\n| autoPlay    | boolean                        | false     | Won't work on most mobile devices |\n| loop        | boolean                        | false     | |\n| muted       | boolean                        | false     | |\n| volume      | number                         | 1.0       | Won't work on most mobile devices |\n| crossOrigin | string                         | undefined | |\n| mediaGroup  | string                         | undefined | |\n\n\nMore native attributes detail: [MDN Audio element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio)\n\nThe `controls` attribute defaults to `false` and should never be changed to `true` because this library is already providing UI.\n\n### UI/UX Props\n\n| Props                    | Type              | Default | Note |\n| ------------------------ | ----------------- | ------- | ---- |\n| showSkipControls         | boolean           | false   | Show Previous/Next buttons |\n| showJumpControls         | boolean           | true    | Show Rewind/Forward buttons |\n| showDownloadProgress     | boolean           | true    | Show download progress over progress bar |\n| showFilledProgress       | boolean           | true    | Show filled (already played) area on progress bar |\n| showFilledVolume         | boolean           | false   | Show filled volume area on volume bar |\n| hasDefaultKeyBindings    | boolean           | true    | Whether has default keyboard shortcuts |\n| autoPlayAfterSrcChange   | boolean           | true    | Play audio after `src` is changed, no matter `autoPlay` is `true` or `false` |\n| volumeJumpStep           | number            | 0.1     | Indicates the volume jump step when pressing up/down arrow key, volume range is `0` to `1` |\n| progressJumpStep         | number            | 5000    | **Deprecated, use progressJumpSteps.** Indicates the progress jump step (ms) when clicking rewind/forward button or left/right arrow key |\n| progressJumpSteps        | object            | `{ backward: 5000, forward: 5000 }`    | Indicates the progress jump step (ms) when clicking rewind/forward button or left/right arrow key|\n| progressUpdateInterval   | number            | 20      | Indicates the interval (ms) that the progress bar UI updates,  |\n| listenInterval           | number            | 1000    | Indicates the interval (ms) to call the `onListened` prop during playback |\n| defaultCurrentTime       | ReactNode         | '--:--' | Default display for audio's current time before src's meta data is loaded |\n| defaultDuration          | ReactNode         | '--:--' | Default display for audio's duration before src's meta data is loaded |\n| timeFormat               | 'auto' \\| 'mm:ss'\u003cbr\u003e\\| 'hh:mm:ss' | 'auto' | Time format for both current time and duration. `'auto'` means when duration is greater than one hour, time format is `hh:mm:ss`, otherwise it's `mm:ss` |\n| header                   | ReactNode         | null    | Header of the audio player |\n| footer                   | ReactNode         | null    | Footer of the audio player |\n| layout                   | 'stacked' \\| 'horizontal' \\|\u003cbr\u003e'stacked-reverse' \\|\u003cbr\u003e'horizontal-reverse' | 'stacked' | [Overall layout](https://lhz516.github.io/react-h5-audio-player/?path=/docs/layouts-advanced) of the audio player |\n| customIcons              | [CustomIcons](https://github.com/lhz516/react-h5-audio-player/blob/fa1a61eb7f77146e1ce4547a14181279be68ecfd/src/index.tsx#L99) | {}      | [Custom icons](https://lhz516.github.io/react-h5-audio-player/?path=/docs/layouts--custom-icons) to replace the default ones |\n| customProgressBarSection | [Array\u003cstring \\|\u003cbr\u003eReactElement\u003e](https://github.com/lhz516/react-h5-audio-player/blob/fa1a61eb7f77146e1ce4547a14181279be68ecfd/src/index.tsx#L91) | [CURRENT_TIME,\u003cbr\u003ePROGRESS_BAR,\u003cbr\u003eDURATION] | [Custom layout](https://lhz516.github.io/react-h5-audio-player/?path=/docs/layouts-advanced) of progress bar section |\n| customControlsSection    | [Array\u003cstring \\|\u003cbr\u003eReactElement\u003e](https://github.com/lhz516/react-h5-audio-player/blob/fa1a61eb7f77146e1ce4547a14181279be68ecfd/src/index.tsx#L92) | [ADDITIONAL_CONTROLS,\u003cbr\u003eMAIN_CONTROLS,\u003cbr\u003eVOLUME_CONTROLS] | [Custom layout](https://lhz516.github.io/react-h5-audio-player/?path=/docs/layouts-advanced) of controls section |\n| customAdditionalControls | [Array\u003cstring \\|\u003cbr\u003eReactElement\u003e](https://github.com/lhz516/react-h5-audio-player/blob/fa1a61eb7f77146e1ce4547a14181279be68ecfd/src/index.tsx#L93) | [LOOP] | [Custom layout](https://lhz516.github.io/react-h5-audio-player/?path=/docs/layouts-advancedd) of additional controls |\n| customVolumeControls     | [Array\u003cstring \\|\u003cbr\u003eReactElement\u003e](https://github.com/lhz516/react-h5-audio-player/blob/fa1a61eb7f77146e1ce4547a14181279be68ecfd/src/index.tsx#L94) | [VOLUME] | [Custom layout](https://lhz516.github.io/react-h5-audio-player/?path=/docs/layouts-advanced) of volume controls |\n| i18nAriaLabels           | [I18nAriaLabels](https://github.com/lhz516/react-h5-audio-player/blob/e67fe0cdd39d00490b7396ebdc46357815ecb227/src/index.tsx#L138)| [I18nAriaLabels](https://github.com/lhz516/react-h5-audio-player/blob/e67fe0cdd39d00490b7396ebdc46357815ecb227/src/index.tsx#L183) | A configuration object to overwrite the default `aria-label` on the action buttons |\n| mse                      | Object           | null     | A configuration object so the player can play audio chunks, MSE streams and encrypted audio (See [section about Media Source Extensions](#media-source-extensions-and-encrypted-media-extensions) in this Readme) |\n| mse.srcDuration          | number           | -        | The complete duration of the MSE audio chunks together (this is a key of the _mse_ prop) |\n| mse.onSeek               | Function (Event) | -        | The callback to be used when seek happens (this is a key of the _mse_ prop) |\n| mse.srcDuration          | number           | -        | The callback to be used when encrypted audio is detected and needs to be decrypted (this is a key of the _mse_ prop) |\n\n### Event Props\n\nSupported media events: `onPlay`, `onPause`, `onEnded`, `onSeeking`, `onSeeked`, `onAbort`, `onCanPlay`, `onCanPlayThrough`, `onEmptied`, `onError`, `onLoadStart`, `onLoadedMetaData`, `onLoadedData`, `onPlaying`, `onSuspend`, `onWaiting`, `onVolumeChange`\n\nDocs: [Media Events | MDN](https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Media_events)\n\nNote: `onTimeUpdate` is not supported. Please use `onListen` with `listenInterval` for better performance.\n\n#### Other events\n\n| Props                    | Type              | Default | Note |\n| ------------------------ | ----------------- | ------- | ---- |\n| onClickPrevious          | Function (Event)  | null    | Called when click Previous button |\n| onClickNext              | Function (Event)  | null    | Called when click Next button |\n| onListen                 | Function (Event)  | null    | Called every `listenInterval` milliseconds during playback |\n| onPlayError              | Function (Error)  | null    | Called when there's error invoking `audio.play()`, it captures error that `onError` won't catch |\n| onChangeCurrentTimeError | Function ()       | null    | Called when dragging progress bar or press rewind/forward while the audio hasn't loaded yet |\n\n## UI Overwrites\n\nBesides using props to change UI, React H5 Audio Player provides built-in class names and SASS/LESS variables for developers to overwrite.\n\n### SASS variables\n\n```scss\n$rhap_theme-color: #868686 !default;   // Color of all buttons and volume/progress indicators\n$rhap_background-color: #fff !default; // Color of the player background\n$rhap_bar-color: #e4e4e4 !default;     // Color of volume and progress bar\n$rhap_time-color: #333 !default;       // Font color of current time and duration\n$rhap_font-family: inherit !default;   // Font family of current time and duration\n```\n\nFor LESS variables, just replace `$` with `@`. This library supports both.\n\n### Status class names\n\nThere are some status class names on the audio player's wrapper div. They can be used for overwriting styles.\n\n| className                   | Description        | \n| --------------------------- | ------------------ | \n| rhap_loop--on               | Loop is on         | \n| rhap_loop--off              | Loop is off        |\n| rhap_play-status--paused    | Paused status      |\n| rhap_play-status--playing   | Playing status     |\n\nFor example:\n```scss\n.rhap_play-status--paused .rhap_progress-bar {\n  // Overwrite the progress bar style while the audio is paused\n}\n```\n\n## Advanced Usage\n\n### Access to the audio element\n\nYou can get direct access to the underlying audio element. First get a ref to ReactAudioPlayer:\n\n```jsx\nthis.player = createRef()\n\n\u003cReactAudioPlayer ref={this.player} /\u003e\n```\n\nThen you can access the audio element like this:\n\n`this.player.current.audio.current`\n\n### Media Source Extensions and Encrypted Media Extensions\n\nYou can use [Media Source Extensions](https://developer.mozilla.org/en-US/docs/Web/API/Media_Source_Extensions_API) and [Encrypted Media Extensions](https://developer.mozilla.org/en-US/docs/Web/API/Encrypted_Media_Extensions_API) with this player. You need to provide the complete duration, and also a onSeek and onEncrypted callbacks. The logic for feeding the audio buffer and providing the decryption keys (if using encryption) must be set in the consumer side. The player does not provide that logic. Check the [StoryBook example](https://github.com/lhz516/react-h5-audio-player/blob/master/stories/mse-eme-player.tsx) to understand better how to use.\n\n## Release Notes\n\nhttps://github.com/lhz516/react-h5-audio-player/releases\n\n## How to contribute\n\nIssues and PR's are welcome.\n\n## Credits\n\n- Inspired by [React Audio Player](https://github.com/justinmc/react-audio-player).\n- Icon wrapper [iconify](https://iconify.design/)\n- Icons [Material Design Icons](https://github.com/Templarian/MaterialDesign)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flhz516%2Freact-h5-audio-player","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flhz516%2Freact-h5-audio-player","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flhz516%2Freact-h5-audio-player/lists"}