@hyperstream/videoplayer

@hyperstream/videoplayer is a ready-to-use video player for React apps and regular websites.

You can use it in two ways:

1. In a React or Next.js app by installing the npm package.
2. On any website with a single script tag and a custom HTML element.

It supports video playback, audio playback, captions, chapters, playlists, brand colors, portrait layouts, and direct media files.

Before You Start

You only need three things to get going:

1. A video source.
2. A title you want to show on the player.
3. An optional brand color such as #00704A.

Your video source can be one of these:

1. A Hyperstream or FAHS video URL.
2. A direct HLS stream URL that ends with .m3u8.
3. A direct media file such as .mp4, using directSrc in React or direct-src in HTML.

If you are not sure where to start, use the website example in the next section. It is the fastest option.

Fastest Setup: Any Website, No React Required

Copy and paste this into your page:

<script src="https://videoplayer.flowautomate.com/player.js"></script>

<hyperstream-video-player
  src="https://fahs.io/your-video"
  title="My Video"
  brand-color="#00704A"
  show-controls="true"
  show-title="true"
></hyperstream-video-player>

Now replace these values:

1. Replace https://fahs.io/your-video with your own video URL.
2. Replace My Video with the title you want people to see.
3. Replace #00704A with your own brand color, if you want one.

That is enough for a working player.

If You Only Have a Video Slug

You can use the short slug with q instead of a full URL:

<script src="https://videoplayer.flowautomate.com/player.js"></script>

<hyperstream-video-player
  q="your-video-slug"
  title="My Video"
  brand-color="#00704A"
></hyperstream-video-player>

If You Want to Play a Direct MP4 or HLS File

Use direct-src when you want to bypass Hyperstream or FAHS resolution and load the file directly:

<script src="https://videoplayer.flowautomate.com/player.js"></script>

<hyperstream-video-player
  direct-src="https://example.com/video.mp4"
  title="Product Demo"
  poster="https://example.com/poster.jpg"
></hyperstream-video-player>

React Setup

Step 1: Install the Package

npm install @hyperstream/videoplayer

Step 2: Import the Player and Its Styles

import { HyperstreamVideoPlayer } from "@hyperstream/videoplayer";
import "@hyperstream/videoplayer/dist/styles.css";

Step 3: Paste the Component

import { HyperstreamVideoPlayer } from "@hyperstream/videoplayer";
import "@hyperstream/videoplayer/dist/styles.css";

export default function App() {
  return (
    <HyperstreamVideoPlayer
      hyperstreamUrl="https://fahs.io/your-video"
      title="My Video"
      brandColor="#00704A"
      showControls
      showTitle
    />
  );
}

If you already have a direct media file, use directSrc instead:

<HyperstreamVideoPlayer
  directSrc="https://example.com/video.mp4"
  title="Product Demo"
  thumbnail="https://example.com/poster.jpg"
/>

Common Copy-Paste Examples

Portrait Video

<HyperstreamVideoPlayer
  hyperstreamUrl="https://fahs.io/your-video"
  title="Mobile Story"
  aspectRatio="9:16"
  maxStageHeight="70vh"
  brandColor="#0F766E"
/>

Start Muted for Autoplay

<HyperstreamVideoPlayer
  hyperstreamUrl="https://fahs.io/your-video"
  title="Homepage Banner"
  autoplay
  muteOnStart
/>

Plain HTML Embed With More Options

<script src="https://videoplayer.flowautomate.com/player.js"></script>

<hyperstream-video-player
  src="https://fahs.io/your-video"
  title="Training Video"
  artist="Flow Automate"
  poster="https://example.com/poster.jpg"
  brand-color="#0F766E"
  aspect-ratio="16:9"
  max-stage-height="75vh"
  autoplay="false"
  mute-on-start="false"
  show-controls="true"
  initial-volume="80"
  playback-speed="1"
></hyperstream-video-player>

React Props

These are the props most people use first.

| Prop | Type | What it does | | --- | --- | --- | | hyperstreamUrl | string | Main Hyperstream or FAHS video URL. | | url | string | Alias for hyperstreamUrl. Use either one, not both. | | directSrc | string | Direct media file URL such as MP4 or HLS. | | title | string | Main title shown on the player. | | artist | string | Smaller secondary line under the title. | | thumbnail | string | Poster image shown before playback. | | poster | string | Alias for the poster image. | | watermark | string | Watermark image shown on the player. | | brandColor | string | Main accent color. | | primaryColor | string | Alias for the accent color. | | autoplay | boolean | Starts playback as soon as the browser allows it. | | muted | boolean | Starts muted. | | muteOnStart | boolean | Forces the first play to start muted. | | controls | boolean | Enables the player controls. | | showControls | boolean | Shows or hides the custom control bar. | | showTitle | boolean | Shows or hides the title area. | | loop | boolean | Restarts automatically when playback ends. | | initialVolume | number | Starting volume from 0 to 100. | | playbackSpeed | number | Starting speed from 0.25 to 4. | | objectFit | "contain" \| "cover" \| "fill" \| "none" \| "scale-down" | Controls how the video fits inside the player area. | | aspectRatio | number \| string | Forces the player shape, for example "16:9", "9:16", or 1.777. | | maxStageHeight | string | Limits the maximum height, for example "70vh". | | overlayColor | "dark" \| "light" | Changes the overlay style used on controls and text. | | skin | string | Chooses the player UI style. | | apiKey | string | Sends an API key for protected streams. | | playlist | PlaylistConfig | Loads multiple items into a playlist. |

All of these props are reactive. If you change them later, the player updates without needing to remount.

HTML Attributes For the Website Version

Use these on <hyperstream-video-player>.

| Attribute | What it does | | --- | --- | | src | Main video URL. | | q | Short video slug. | | direct-src | Direct media file URL. | | title | Main title shown on the player. | | artist | Secondary text shown under the title. | | poster | Poster image URL. | | brand-color | Main accent color. | | primary-color | Alias for the accent color. | | secondary-color | Secondary brand color. | | text-color | Text color override. | | autoplay | true or false. | | muted | true or false. | | mute-on-start | true or false. | | controls | true or false. | | show-controls | true or false. | | show-title | true or false. | | loop | true or false. | | initial-volume | Number from 0 to 100. | | playback-speed | Number from 0.25 to 4. | | object-fit | contain, cover, fill, none, or scale-down. | | aspect-ratio | For example 16:9, 9:16, 1:1, or 1.777. | | max-stage-height | For example 70vh or 100%. | | skin | UI skin name. | | api-key | API key for protected streams. |

React Ref API

If you need buttons outside the player, use a ref.

import { useRef } from "react";
import {
  HyperstreamVideoPlayer,
  type HyperstreamVideoPlayerRef,
} from "@hyperstream/videoplayer";
import "@hyperstream/videoplayer/dist/styles.css";

export default function Example() {
  const playerRef = useRef<HyperstreamVideoPlayerRef>(null);

  return (
    <>
      <HyperstreamVideoPlayer
        ref={playerRef}
        hyperstreamUrl="https://fahs.io/your-video"
        title="Demo"
      />

      <button onClick={() => void playerRef.current?.play()}>Play</button>
      <button onClick={() => playerRef.current?.pause()}>Pause</button>
      <button onClick={() => playerRef.current?.seek(30)}>Go to 0:30</button>
    </>
  );
}

Available Ref Methods

| Method | What it does | | --- | --- | | play() | Starts playback. | | pause() | Pauses playback. | | seek(time) | Jumps to a time in seconds. | | setVolume(volume) | Sets volume from 0 to 1. | | setPlaybackRate(rate) | Changes speed from 0.25 to 4. | | setMuted(muted) | Mutes or unmutes the player. | | getCurrentTime() | Returns the current playback time in seconds. | | getDuration() | Returns the full duration in seconds. | | getHlsInstance() | Returns the underlying HLS instance for advanced use. | | nextTrack() | Plays the next playlist item. | | prevTrack() | Plays the previous playlist item. | | selectPlaylistItem(item) | Loads a specific playlist item object. | | playItemById(id) | Loads a playlist item by its id. | | closeDock() | Closes the dock panel. | | setDockTab(tab) | Switches the dock tab to A, B, or C. | | setActiveCaption(language) | Changes the active caption or transcript language. |

JavaScript API For the HTML Version

Once the web component is on the page, you can control it in normal JavaScript.

<script>
  const player = document.querySelector("hyperstream-video-player");

  player.play();
  player.pause();
  player.seek(30);
  player.setVolume(0.8);
  player.setPlaybackRate(1.25);
  player.setMuted(true);
  player.mute();
  player.unmute();
</script>

Events For the HTML Version

The web component emits browser events that you can listen for.

<script>
  const player = document.querySelector("hyperstream-video-player");

  player.addEventListener("ready", () => {
    console.log("Player ready");
  });

  player.addEventListener("play", () => {
    console.log("Playing");
  });

  player.addEventListener("pause", () => {
    console.log("Paused");
  });

  player.addEventListener("timeupdate", (event) => {
    console.log(event.detail.currentTime, event.detail.duration);
  });
  
  player.addEventListener("error", (event) => {
    console.error(event.detail);
  });
</script>

| Event | What it means | | --- | --- | | ready | The player has loaded and is ready. | | play | Playback has started. | | pause | Playback has paused. | | ended | Playback reached the end. | | timeupdate | Current time changed. event.detail contains currentTime and duration. | | volumechange | Volume or mute state changed. event.detail contains volume and muted. | | ratechange | Playback speed changed. event.detail contains rate. | | error | An error happened. event.detail contains the error data. |

Troubleshooting

The player appears, but the video does not load

Check the source first.

1. Make sure the URL is correct.
2. If you are using directSrc or direct-src, make sure the file is publicly reachable.
3. If the stream is protected, pass the correct apiKey.

Autoplay does not work

Most browsers block autoplay with sound.

Use one of these approaches:

1. Set muteOnStart in React.
2. Set mute-on-start="true" in HTML.

The player looks unstyled in React

Make sure you imported the stylesheet:

import "@hyperstream/videoplayer/dist/styles.css";

Chapters, transcript, or playlist do not appear

Those panels only appear when the source actually includes that data.

I am not technical. What should I try first?

Use the website version with the <script> tag and <hyperstream-video-player> example from this README. Replace only these three values first:

1. src
2. title
3. brand-color

Once that works, add the other settings one by one.

License

MIT