@github/media-players v1.1.0

Well hello hello! 👋 And welcome to the amazing world of GitHub's very own custom HTML Video and Audio player.✨ Written to fully utilise the power of the amazing GitHub Catalyst.

Why we did it, you might ask?

• We want to have full control over the player and it's optimisation
• With that said, we want a GitHub branded player that can be easily adapted to GitHub's different sub-brands
• And seriously, embedding third party players is lazy and brings performance costs and security concerns

Video Player <video-player>

Audio Player <audio-player>

🧩 Features

*no UI - means that the feature exists in the code but we will need to iterate the design, especially for mobile screens in order for this UI to be implemented.

⌨️ Keyboard controls

• Play/Pause Space
• Skip forward Arrow Right
• Skip backward Arrow Left
• Volume Up Arrow Up
• Volume Down Arrow Down
• Mute toggle M
• Fullscreen toggle F
• Captions toggle C

These are the most common keyboard controls that appear on platforms like Youtube, Vimeo and other popular custom players.

📹 Live streaming guide

HLS support

Supported natively only in Safari, needs a hls.js third party dependancy for HLS to be enabled for Chrome(ium) and Firefox browsers with a few lines of code in the onConnected callback.

⚠️ Note: Add HLS support only if and where needed - this dependancy will increase the bundle size and reduce the page performance.

To enable HLS for Chrome(ium) and Firefox, follow these easy steps steps:

1. npm install --save hls.js
2. import Hls from 'hls.js' into _scripts/github/marketing/audio-player.ts #L2
3. Paste the following code into connectedCallback callback here _scripts/github/marketing/audio-player.ts. #61,#68

const hlsSource = this.media.querySelector<HTMLElement>('source[type="application/x-mpegurl"], source[type="application/vnd.apple.mpegurl"], source[type="audio/mpegurl"]')
if (hlsSource && !this.media.canPlayType('application/vnd.apple.mpegurl') && Hls && Hls.isSupported()) {
  const hls = new Hls()
  const src = hlsSource.getAttribute('src')
  if (!src) return
  hls.loadSource(src);
  hls.attachMedia(this.media);
}

MPEG-DASH support

Not supported natively by browsers. Third party dash.js dependancy is needed for this type of protocol to work.

⚠️ Note: Add MPEG-DASH support only if and where needed - this dependancy is ~800KB in size and minified!!!

To enable MPEG-DASH, follow these easy steps steps:

1. Download dash.all.min.js from https://github.com/Dash-Industry-Forum/dash.js/
2. Include <script async src="assets/js/dash.all.min.js" ></script> wherever you want - P.S. I didn't succeed in using this as a NPM package, their guide was poor and after failing to include it's index.js from node_modules I stopped trying 😬
3. Add data-dashjs-player attribute to the <video> element of the <video-player> template

🌎 Browser support

Tested in BrowserStack

Desktop

• Safari 13.1+
• Chrome 80+ / Edge 80+
• Firefox 78+
• Opera 80+

Mobile

Tested and working on a low-end Android phone: Nokia 3; Android 9; Chrome 80

• iOS Safari 13.4+
• Chrome 80+
• Firefox 78+
• Samsung Internet 17+
• UC Browser ❌ (whatever this is)

💻 Local Development

New to running code on your laptop here at GitHub? Talk to @github/marketing-platform-services and we'll help get you sorted before diving into these setup instructions.

Install this project's dependencies by running the following from Terminal:

$ script/bootstrap

To start the server and view this site locally, run:

$ script/server

This will compile the structure of the site for you and start a local server at http://localhost:4000/. Jekyll will watch HTML updates for changes, automatically rebuilding the site as needed.

Then open a new Terminal window and run:

$ npm run watch

This will run Rollup with a watch option and compile and watch for changes of the SASS and JS/TS files. Located in _sass and _scripts respectively.

Dependencies

• @github/catalyst - 1.6.0+
• @primer/css - 19.0.0+

Structure

VideoPlayer

_includes/video-player.html

AudioPlayer

_includes/audio-player.html

Styles

_sass/github/marketing/components/media-players.scss

Scripts

VideoPlayer inherits all of the AudioPlayer functionality and adds only features related to video, like fullscreen, hiding controls, captions, poster and a big overlaying play button.

VideoPlayer

_scripts/github/marketing/audio-player.ts

AudioPlayer

_scripts/github/marketing/video-player.ts

New to @github/catalyst?

GitHub Catalyst is an amazing framework that minimises coding effort when creating custom elements. It also makes the code look much more cleaner and therefore more readable and easier to maintain.

Most importantly it allows us to lazy define the custom element so it's constructed only when the element becomes available in the DOM:

  lazyDefine('audio-player', () => import('./github/marketing/audio-player'))
  lazyDefine('video-player', () => import('./github/marketing/video-player'))

If you are new to Catalyst, we have included the simplest video player custom element micro-video-player as a demo to get you started quickly. It's functionality is basically click to play and click to pause.

_includes/micro-video-player.html

_scripts/github/marketing/micro-video-player.ts

📝 TO DO:

• Issue with 206 http response - partial content
• Accessibility
  • VideoPlayer video download
  • VideoPlayer and AudioPlayer playback speed selector
  • VideoPlayer captions language selector
  • VideoPlayer video quality selector - this will need a system to load, probably in an unattached <video> element, and replace the existing one so the change would appear on the fly.
• Integrate analytics
• VideoPlayer iOS fake fullscreen

💖 Design Credits

Audio Player

Initially created for the purposes of ReadME Project Podcasts, but is also used in marketing pages like: /about/diversity/report and /about/diversity/communities-of-belonging/blacktocats.

Designed by Matt Lee @mattjohnlee

Video Player

Initially created as a BaM Passion week: August 2022 project and to be included initially in ReadME Project and other marketing pages.

Designed by Mary He @maryhehehe