Shikwasa is an web audio player born for podcast. If you're tired of using music players as a substitute to play podcast, you've come to the right place. SAY NO to players that does not even support podcast common features!
- 🚀 Ultra lightweight
- 🐣 Dependency free
- 🎬 Podcast chapters
- 🏎 Playback speed control
- 🎮 Skip forward/backward
- 👓 Accessibility-aware
- 🌙 Dark Mode
- SSR compatible
📖Table of Contents
npm install shikwasa
Also available on CDN: https://www.jsdelivr.com/package/npm/shikwasa
include stylesheet and script
Specify a container for the player to be injected into. For example:<!-- this is where the player will be injected -->
Create an instance of the player// an example with basic init optionsconst player =documentaudio:title: 'Hello World!'artist: 'Shikwasa FM'cover: 'image.png'src: 'audio.mp3'
Any child nodes inside
containerwill be cleared upon the time Shiwkasa mounts.
If you use module system, import like this:const player = options
To use the Chapter feature, you need to import the chapter script and stylesheets as well. View details
Start playing the current audio. Updating audio via this method is deprecated, please use
Pause the current audio.
Toggle audio play state between play and pause.
Seek the audio to the new time.
time is a number that specifies target playback time in seconds.
audio object in will replace the current audio source.
Destroy the player instance.
Register an event listener. Supported events see: Events
The current playback time. Similar to the native
The current mute state of the player. Similar to the native
HTMLMediaElement.muted, except that
muted's value will not be affected when audio source is updated.
The current playbackRate of the player. Similar to the native
HTMLMediaElement.playbackRate, except that
playbackRate's value will not be affected when audio source is updated.
audio.duration || options.audio.duration
(Required) The target audio to be played. If
duration is passed in, players with
preload option set to
none will have a audio duration time display before the audio metadata is fetched. However, after the audio metadata is loaded, this prop will be ignored.
audio:title: Stringartist: Stringcover: Stringsrc: Stringduration: Number // optionalalbum: String // optional, album text will only display in Mediametadata, not visible in player UI.
(Optional) The container element for the player. If
document is not available in the env, pass a function that will return the container element.
() => document.querySelector('body')
(Optional) Whether player should be fixed to viewport.
fixed:type: 'auto'position: 'bottom'
(Optional) Theme color of the player.
(Optional) If audio should autoplay on load. ⚠️Note: Chrome and Safari disable audio autoplay unless
muted is set to
true by default. To comply with this policy, see details in Chrome Developers and Webkit Announcement.
Whether audio should be muted by default. Similar to HTMLMediaElement's
(Optional) Choose from
none. For details view MDN Doumentation.
parser is used, the audio will be requested immediately on page load for the parser to work properly, even if
preload is set to
(Optional) The playback speed range. Each value of the array should be between the range of 0.25 to 5.0, or will likely be ignored by certain browsers.
[0.5, 0.75, 1.25, 1.5]
(Optional) Whether the current audio source is download-able. When set to
true, the player will provide an anchor with
downlaod attribute and
href set to
href will not prompt download due to anchor's nature, but you can offer an alternative
data: url or a same-origin direct download link(DDL).
download: true// or with a urldownload: 'data:audio/mp3;base64,...'
(Optional) To focus on the player itself as well as to maintain Shikwasa as efficient as possible, we don't extract data from audio files. If you don't have control over the chapter data but would like to implement chapter feature, we support using
jsmediatags as an external parser to parse the current audio's metadata.
It will read the audio's
chapters, meaning you don't have to provide these four properties into
audio manually unless you preferred your own. Priority: property values passed to
audio > parsed data.
npm install jsmediatags //
...parser: jsmediatagsaudio: src: ...
audio.src is not of the same origin, proper CORS configuration will be needed to use the parser.
jsmediatags limitation, relative urls are not supported. Please use absolute urls for
Support all HTMLMediaElement native events.
audioupdate: fired when audio source is updated.
audioparse: fired when audio file data is parsed.
Shikwasa will support chapter display and seeking with the chapter plugin. To use:
Register the chapter plugin before creating a Shikwasa instance.Shikwasa...
This does not guarantee that the audio will display chapters. To display chapters, you need to provide chapter data to the player.
If you don't have direct access to the chapter data, Shikwasa has built-in support to work with jsmediatags to read and extract the data from the audio file;
audio:...chapters: // Array, optionaltitle startTime endTime // the first chaptertitle startTime endTime // the second chatper
The structure of a single chapter object:
Property Type Description title String chapter title startTime Number chapter start time in seconds endTime Number chapter end time in seconds
endTimeshould be the same as
startTimeof the next chapter.
(2) To use an external parser, pass
parseroptions. How to use a parser?
(1) will take higher priority.
Registering Chapter plugin will empower Shikwasa instance with the following API:
Seek the audio to the target chapter.
index is the index of of
Chapter metadata of the current audio, if any. See Chapter.
Indicate which chapter is currently on play, if any. See Chapter.
chapterchange: fired when
- supporting audio id3 metadata --currently working on this one
- cleaner & sleeker interface
- dark mode
- a complete rewrite
- keyboard support
- rewrittern with Typescript
- podcast playlist
What about the weird name of this project?
Shikwasa is the name of a popular citrus fruit from Okinawa, Japan. 🍊
Love it, name after it.