npm package: @hyperstream/videoplayer
Description: Hyperstream Video Player React Component
Latest version: 0.3.3

# @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:

```html
<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:

```html
<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:

```html
<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

```bash
npm install @hyperstream/videoplayer
```

### Step 2: Import the Player and Its Styles

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

### Step 3: Paste the Component

```tsx
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:

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

## Common Copy-Paste Examples

### Portrait Video

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

### Start Muted for Autoplay

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

### Plain HTML Embed With More Options

```html
<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.

```tsx
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.

```html
<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.

```html
<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:

```tsx
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