Skip to content
An audio player born for podcast
JavaScript HTML CSS
Branch: master
Clone or download
Latest commit 2f938ed Nov 10, 2019

README.md

shikwasa branding image


npm size license

About

Shikwasa is an 🚀ultra-lightweight, dependency-free web audio player born for podcast. You may enjoy a podcast with occasional playback controls to get the best listening experience, just like I do - tweaking with handy forward/backward or speed buttons. But chances are traditional html audio players don't offer them - who would play music on 1.5x speed?

If you are looking for the full power of Shikwasa player, but prefer customizing structures and styles of your own, check out Shisa

...wait, explain this weird name to me! In case you wonder, Shikwasa is the name of a popular citrus fruit from Okinawa, Japan. 🍊

➡️DEMO here⬅️

⚠️Note: The current documentation is in sync with this repo and may be ahead of its npm released version. For version-specific documentation, please view: v1.0.6

📖Table of Contents

Installation

npm install shikwasa

Usage

  1. include stylesheet and script

     <head>
       <link rel="stylesheet" href="shikwasa.min.css">
     </head>
     <body>
       <script src="shikwasa.min.js"></script>
     </body>
  2. Specify a container for the player to be injected into. For example:

     <div class="elementOfYourChoice">
       <!-- this is where the player will be injected -->
     </div>
  3. Create an instance of the player

    // an example with basic init options
    
    const player = new Shikwasa({
      container: document.querySelector('.elementOfYourChoice'),
      audio: {
        title: 'Hello World!',
        artist: 'Shikwasa FM',
        cover: 'image.png',
        src: 'audio.mp3',
      },
    })

If container has any child nodes, it will be cleared before Shikwasa mounts.

  1. If you use module system, import like this:

     import 'shikwasa/dist/shikwasa.min.css'
     import Shikwasa from 'shikwasa'
    
     const player = new Shikwasa(options)

API

Methods

.play(audio)

If no parameter supplied, calling it will play the current audio. Passing an audio object in will replace the previous audio source, and play the new one immediately.

// play with the current audio source
player.play()

// pass an audio object to play with the new audio source immediately
player.play({
  title: 'Embrace the universe with a cup of shikwasa juice',
  artist: 'Shikwasa',
  cover: 'image.png',
  src: 'sourceAudio.mp3'
})

.pause()

Pause the current audio.

.toggle()

Toggle audio play state between play and pause.

.seek(time)

time is a number that specifies target playback time. Calling this method with time will seek the audio to the new time.

.destroy()

Destroy the player instance.

.on(event, callback)

Register an event listener. Supported events see: Events

Properties

.currentTime

A read-only property that indicates the current playback time. Similar to the native htmlMediaElement.currentTime.

Options

Audio

(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.

  • required
  • type: Object
  • default: null
  • properties:
  audio: {
    title: String,
    artist: String,
    cover: String,
    src: String,
    duration: Number,  // optional
  }

container

(Optional) The container element for the player.

  • type: HTMLCollection
  • default: document.querySelector('body')

fixed

(Optional) Whether player should be fixed to viewport.

  • type: Object
  • default:
fixed: {
  type: 'auto',
  position: 'bottom',
}
  • details:
Property Type Description
type String either auto, static or fixed
auto: player position is controlled by media queries. Normally the player stays static, but on small screens it will be fixed to viewport
static: force the player to remain static regardless of screen width
fixed: force the player to fix to viewport
position String either bottom or top
⚠️Note: position will be ignored when type is set to static

themeColor

(Optional) Theme color of the player.

  • type: String
  • default: #00869B

autoplay

(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.

  • type: Boolean
  • default: false

muted

Whether audio should be muted by default. Right now this will not have any impact on audio object's defaultMuted property.

  • type: Boolean
  • default: false

preload

(Optional) Choose from auto, metadata and none. For details view MDN Doumentation.

  • type: String
  • default: metadata

speedOptions

(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

  • type: Array
  • default: [0.5, 0.75, 1.25, 1.5]

download

(Optional) Whether the current audio file is download-able. When set to true, a download button shows up on the player.

  • type: Boolean
  • default: false

Events

Support all htmlMediaElement native events.

Roadmap

Under v1.0.0:

  • exposing native audio events
  • API support for seeking and audio's currentTime property, allowing to seek from a certain timestamp & share episode content with timestamp
  • automatically pausing other Shikwasa players in the same page while one is playing
  • improving keyboard support for situation where multiple Shikwasa players are mounted in the same page
  • supporting audio id3 metadata
  • cleaner & sleeker interface
  • dark mode

Others:

  • podcast playlist

License

MIT

You can’t perform that action at this time.