Integration and setup

PN Player ships as a single JavaScript bundle and stylesheet hosted on the PN Player CDN. You load both, add a container element and call window.pnplayer() with your options.

Each customer receives their own versioned build at https://cdn.pnplayer.com/<client>/<version>/. Copy the exact <script> and <link> tags for your latest build from your builds page at https://cdn.pnplayer.com/builds/index.html?client=<client>. The file names below are placeholders.

Steps

Include PN Player resources in your page head

<script async src="https://cdn.pnplayer.com/<client>/<version>/index-xxxxxx.js" type="module"></script>
<link href="https://cdn.pnplayer.com/<client>/<version>/index-xxxxxx.css" rel="stylesheet" />

Create the container elements

Add a wrapper with the id pnplayer and an inner element for the player to mount on.

<div id="pnplayer">
  <div id="pn-player"></div>
</div>

Keep the outer #pnplayer wrapper. The stylesheet is scoped to it, so the player renders unstyled without it. The wrapper is sized to the full width of its parent with a 16:9 aspect ratio.

Initialise the player

Call pnplayer with the id of the inner element and your options. Wait for the bundle to load first, for example inside window.onload.

<script>
  window.onload = () => {
    const player = window.pnplayer("pn-player", {
      key: "your-api-key",
      sources: [
        {
          title: "Video title",
          src: "https://stream.pnplayer.com/<video-id>/playlist.m3u8",
          textTracks: []
        }
      ]
    });
  };
</script>

The returned object is the player instance you use for controls and events.

Full example

<script>
  const player = window.pnplayer("pn-player", {
    key: "your-api-key",
    source: "Marketing site",
    userId: "user-123",
    playMode: "playlist",
    autoPlay: true,
    muted: false,
    layout: {
      theme: "glassy",
      captionStyles: {
        fonts: [
          { label: "Sans serif", value: "sans-serif" },
        ]
      }
    },
    sources: [
      {
        title: "Episode 1",
        src: "https://stream.pnplayer.com/<video-id>/playlist.m3u8",
        poster: "https://stream.pnplayer.com/<video-id>/thumbnail.jpg",
        thumbnails: "https://stream.pnplayer.com/<video-id>/thumbnails.vtt",
        default: true,
        textTracks: [
          {
            src: "https://stream.pnplayer.com/<video-id>/captions/en.vtt",
            label: "English",
            language: "en",
            kind: "subtitles",
            type: "vtt",
            default: true
          },
          {
            src: "https://stream.pnplayer.com/<video-id>/chapters.vtt",
            kind: "chapters",
            language: "en",
            type: "vtt",
            default: true
          }
        ],
        skipIntro: { start: 0, end: 12, label: "Skip intro" },
        customButtons: [
          { label: "Find more", link: "https://example.com/find-more", openInNewTab: true }
        ]
      },
      {
        title: "Episode 2",
        src: "https://stream.pnplayer.com/<video-id-2>/playlist.m3u8",
        textTracks: []
      }
    ]
  });
</script>

Options

object[]

required

One entry per video. With more than one entry the player shows a playlist menu and, in playlist mode, an Up Next countdown at the end of each video. The entry with default: true plays first, otherwise the first entry does.

Show properties

string

required

Video title. Shown in the player, the playlist menu and the Up Next card, and sent with analytics events.

string

required

HLS playlist URL, for example https://stream.pnplayer.com/<video-id>/playlist.m3u8. Analytics are only recorded for URLs in this format.

object[]

required

Subtitle, caption and chapter tracks. Pass an empty array when there are none.

Show properties

string

required

URL of the track file

string

required

subtitles, captions or chapters

string

Name shown in the captions menu, for example English. Required for subtitle and caption tracks.

string

required

Language code, for example en or en-US

string

default:"vtt"

Track file format: vtt, srt, ass or ssa. ASS and SSA tracks are rendered with full styling, but they cannot be sent to Chromecast.

boolean

default:"false"

Whether this track is enabled when the video loads

string

Image URL shown before playback starts and on the Up Next card

string

URL of a WebVTT thumbnails file for seek previews on the timeline, for example https://stream.pnplayer.com/<video-id>/thumbnails.vtt

boolean

default:"false"

Play this entry first when the player loads

object

Shows a Skip button until playback passes end.

Show properties

number

required

Time in seconds from which the Skip button is shown

number

required

Time in seconds the player seeks to when the button is clicked. The button hides once playback passes this point.

string

default:"Skip"

Button text

object[]

Link buttons shown in the control bar for this video.

Show properties

string

required

Button text

string

required

URL to open when the button is clicked

boolean

default:"false"

Open the URL in a new tab

string

Your API key from the dashboard. Required for playback analytics. Also used to remember each viewer’s caption style preferences in their browser.

string

Label for where the video is being watched, for example Website or iOS app. Reported with analytics. Defaults to the page hostname.

string

Your identifier for the current viewer. Reported with analytics so you can view watch data per user.

string

Set to playlist to auto-advance through sources with an Up Next countdown ten seconds before each video ends. When omitted, viewers can still switch videos from the playlist menu but the player does not auto-advance.

boolean

default:"true"

Start playback as soon as the video can play. Browsers may still require muted: true for autoplay to succeed without user interaction.

boolean

default:"false"

Start playback muted

object

Show properties

string

default:"default"

Visual theme: default, netflix or glassy. Each theme has separate desktop and mobile layouts.

object

Show properties

object[]

Fonts viewers can choose from in the Caption Styles menu. When omitted, only the browser’s sans-serif font is available.

Show properties

string

required

Font display name

string

required

CSS font-family value

string

URL of a web font file to load, for example https://fonts.cdnfonts.com/s/29616/open-dyslexic.woff. If the font fails to load the player falls back to sans-serif.

Analytics

When key is set and the source URL follows the https://<host>/<video-id>/playlist.m3u8 pattern, the player reports playback to PN Player analytics automatically:

a play event on first play
a progress or pause event every ten seconds
an end event when the video finishes
a live heartbeat every five seconds for the live analytics view

Each event carries the video id, title, position, duration, source, userId, a per-page session id and the language of the caption track currently showing.

Caption styling from the VTT file

Add a NOTE karaoke-config block to a WebVTT caption file to style that track. The player reads the block when the track is selected.

WEBVTT

NOTE karaoke-config
font-family: "Open-Dyslexic", sans-serif
font-size: 1.2em
font-weight: 700
active-color: #ffd60a
past-color: #ffffff
future-color: rgba(255, 255, 255, 0.6)
background-color: none

00:00:01.000 --> 00:00:04.000
Once upon a time...

Supported keys are font-size, font-family, font-weight, font-style, text-transform, letter-spacing, active-color, active-shadow, past-color, past-shadow, future-color, future-shadow and background-color. Use background-color: none for a transparent cue background.

Getting started

Features

Player

Guides

Analytics

Integration and setup

Steps

Full example

Options

Analytics

Caption styling from the VTT file

​Steps

​Full example

​Options

​Analytics

​Caption styling from the VTT file

Steps

Full example

Options

Analytics

Caption styling from the VTT file