@hyperstream/player

@hyperstream/player ships the Hyperstream player in two forms:

1. A React package that exports HyperstreamVideoPlayer, HyperstreamAudioPlayer, and HyperstreamStaticMediaViewer.
2. A standalone player.js script that registers the <hyperstream-player> web component for no-build embeds.

Both surfaces support Hyperstream or FAHS URLs, direct HLS or file playback, image and document viewing, captions, chapters, playlists, brand styling, audio mode, and imperative playback control.

Choose the Right Integration

Use the npm package when

• You are building with React or Next.js.
• You want typed props and a typed ref API.
• You want the player inside your component tree instead of inside an iframe.

Use player.js when

• You need to embed the player in plain HTML, a CMS, Webflow, WordPress, or another no-build environment.
• You want a custom element that can be controlled with browser JavaScript.
• You are fine with the player running inside an isolated /watch iframe.

Supported Source Modes

| Source mode | React prop | Web component input | Notes | | --- | --- | --- | --- | | Hyperstream or FAHS URL | hyperstreamUrl or url | src | Main resolved media URL. | | Short slug | Build the URL yourself or pass hyperstreamUrl | q | The web component turns the slug into the /watch?q=... embed route. | | Direct media file | directSrc | direct-src | Use for direct MP4, MP3, WebM, MOV, or HLS .m3u8. | | Playlist | playlist | Not supported as a direct HTML attribute | React-only top-level prop. The web component playlist is normally derived from the resolved source. | | Folder item payload | folderApi plus folderItem | folder-api="true" plus element.folderItem = {...} | Advanced flow for pre-fetched folder content. |

Installation

React / Next.js

npm install @hyperstream/player

Import the package stylesheet once where your app loads global player styles:

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

Standalone Web Component

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

This registers:

• <hyperstream-player>
• <hyperstream-video-player>
• <hp-video-player>

<hyperstream-player> is the primary tag. The others exist for backward compatibility.

Quick Start

React video

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

export default function Demo() {
  return (
    <HyperstreamVideoPlayer
      hyperstreamUrl="https://fahs.io/your-video"
      title="Launch Demo"
      brandColor="#00704A"
      channelId="channel_123"
      studentId="student_456"
      showControls
      showTitle
    />
  );
}

React audio

import { HyperstreamAudioPlayer } from "@hyperstream/player";
import "@hyperstream/player/dist/styles.css";

export default function PodcastCard() {
  return (
    <HyperstreamAudioPlayer
      directSrc="https://example.com/audio/episode-12.mp3"
      title="Episode 12"
      artist="Flow Automate"
      thumbnail="https://example.com/images/episode-12.jpg"
      channelId="channel_123"
      studentId="student_456"
      skin="glass"
    />
  );
}

React static media

import {
  HyperstreamStaticMediaViewer,
  resolveStaticViewerSource,
} from "@hyperstream/player";
import "@hyperstream/player/dist/styles.css";

export default function DocumentPreview() {
  const source = resolveStaticViewerSource(
    {
      url: "https://example.com/documents/guide.pdf",
      media_type: "document",
      fileName: "Guide.pdf",
    },
    "DOCUMENT",
  );

  if (!source) {
    return null;
  }

  return (
    <HyperstreamStaticMediaViewer
      source={source}
      brandColor="#00704A"
      showTitle
      showFullscreen
      showPageNavigation
      showZoom
      allowDownload
    />
  );
}

Web component

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

<hyperstream-player
  src="https://fahs.io/your-video"
  title="Launch Demo"
  brand-color="#00704A"
  channel-id="channel_123"
  student-id="student_456"
  show-controls="true"
  show-title="true"
></hyperstream-player>

Direct HLS or MP4

React:

<HyperstreamVideoPlayer
  directSrc="https://example.com/video/master.m3u8"
  title="Conference Stream"
  thumbnail="https://example.com/video/poster.jpg"
/>

Web component:

<hyperstream-player
  direct-src="https://example.com/video/master.m3u8"
  title="Conference Stream"
  poster="https://example.com/video/poster.jpg"
></hyperstream-player>

React API

The package exports:

• HyperstreamVideoPlayer
• HyperstreamAudioPlayer
• HyperstreamStaticMediaViewer
• type HyperstreamVideoPlayerProps
• type HyperstreamAudioPlayerProps
• type HyperstreamStaticMediaViewerProps
• type HyperstreamVideoPlayerRef
• resolveStaticViewerSource
• buildSignedStaticMediaUrl
• type StaticViewerSource
• type StaticMediaPayload
• type StaticResolvedMediaType
• type StaticDocumentFormat

The audio player extends the shared media props and adds audio-shell specific controls.

Shared React props

These props are accepted by both HyperstreamVideoPlayer and HyperstreamAudioPlayer.

| Prop | Type | How to use it | | --- | --- | --- | | hyperstreamUrl | string | Primary Hyperstream or FAHS URL. Use this for normal hosted playback. | | url | string | Alias for hyperstreamUrl. Prefer hyperstreamUrl in new code. | | directSrc | string | Direct media URL that bypasses Hyperstream resolution entirely. Use for .m3u8, .mp4, .mp3, .webm, and similar direct assets. | | poster | string | Poster image shown before playback starts. For video, this is the static pre-play image. | | thumbnail | string | Thumbnail or artwork fallback used by the player UI, playlist rows, and media metadata. | | watermark | string | Watermark image overlay shown by the player. | | title | string | Primary display title. | | artist | string | Secondary label shown under or beside the title. Useful for speakers, artists, authors, or series names. | | brandColor | string | Main accent color for controls and branded states. | | primaryColor | string | Alias for brandColor. If both are provided, brandColor is the preferred prop to use in new code. | | playlist | PlaylistConfig | React-only playlist input. Use this when you already have multiple playable items and want the dock playlist immediately. | | folderApi | boolean | Enables folder-item mode. Required when you want the player to treat folderItem as the active source. | | folderItem | FolderItemInput \| null | Pre-fetched folder payload item. Only used when folderApi is true. | | autoplay | boolean | Attempts to start playback automatically. Browsers usually require muted playback for autoplay to succeed. | | muted | boolean | Starts the player muted. | | controls | boolean | Enables the player control system. In audio mode this affects whether the full transport UI is shown. | | showControls | boolean | Shows or hides the custom control chrome. | | showTitle | boolean | Shows or hides the title area. | | muteOnStart | boolean | Forces the initial play attempt to start muted. Prefer this over hard-coding muted when you only need autoplay compliance. | | initialVolume | number | Initial volume. 0-100 is preferred. Legacy 0-1 values are also accepted. | | playbackSpeed | number | Initial playback rate. Valid values are effectively clamped to 0.25-4. | | loop | boolean | Restarts the current item automatically after it ends. | | objectFit | "contain" \| "cover" \| "fill" \| "none" \| "scale-down" | Controls how the video fits the stage. contain is safest for mixed aspect ratios. | | aspectRatio | number \| string | Forces the player aspect ratio. Accepts values like 1.777, "16:9", or "9/16". | | maxStageHeight | string | Caps the visible player height. Useful for portrait players or embed layouts, for example "70vh". | | overlayColor | "dark" \| "light" | Chooses the overlay treatment used for titles and controls. | | apiKey | string | Sends an API key when the stream requires protected access. | | containerWidth | number | Advanced layout override. Mostly useful when you are hosting the player inside a custom responsive shell and want to drive breakpoint logic manually. | | isMobile | boolean | Advanced mobile-layout override. Useful for host integrations or testing, not for normal app code. | | onMediaTypeDetected | (mediaType: "AUDIO" \| "VIDEO") => void | Called when the loaded content resolves to audio or video. Useful if you support mixed content sources. | | onPlaybackStateChange | (state: HyperstreamPlaybackState) => void | Called whenever playback state changes. Useful for syncing external UI or analytics. | | onActivePlaylistItemChange | (item: PlaylistItem \| null) => void | Called when the active playlist item changes. | | onPlaylistItemsChange | (items: PlaylistItem[]) => void | Called when playlist items become available or change after source resolution. | | onAssetAuthChange | (auth: { signature: string \| null; ivhex: string \| null }) => void | Called when the player resolves asset auth tokens that protected media or thumbnails may need. | | onTranscriptStateChange | (state: TranscriptStateSnapshot) => void | Called when transcript rows, languages, or the active language changes. | | onAccessDenied | (details: { message: string; status: number }) => void | Called when protected content returns HTTP 403. Use it to render your own access-denied UI. | | onDockStateChange | (state: DockState \| null) => void | Called when the dock opens, closes, or changes. Useful if you want a host shell to mirror the chapters, transcript, or playlist panel outside the player. | | channelId | string | Optional host channel identifier. Included on every player analytics event payload when provided. | | studentId | string | Optional host student identifier. Included on every player analytics event payload when provided. | | analyticsMediaType | MediaType | Advanced analytics override. Use when the player is visually presented as audio but backed by a different transport layer. | | analyticsSessionId | string | Advanced analytics session reuse hook. | | analyticsSender | (payload: PlayerEventPayload) => void | Advanced analytics transport override. Provide this if you already have an upstream analytics pipeline. |

Video-only React props

| Prop | Type | How to use it | | --- | --- | --- | | skin | "default" \| "minimalist" \| "minimal" \| "card" \| "horizontal" \| "bar" \| "modern" \| "classic" \| "neon" \| "glass" \| "expanded" | Video currently has two real visual modes: default and minimalist. Other accepted values currently fall back to the default video presentation. |

Audio-only React props

These are accepted by HyperstreamAudioPlayer in addition to the shared props.

| Prop | Type | How to use it | | --- | --- | --- | | skin | "minimal" \| "card" \| "horizontal" \| "bar" \| "modern" \| "classic" \| "neon" \| "glass" \| "expanded" | Selects the audio UI skin. expanded is the large full-audio presentation. | | externalPlayerRef | React.RefObject<HyperstreamVideoPlayerRef \| null> | Lets the audio shell control an external hidden player instance instead of owning its own internal player. Advanced integration prop. | | playbackStore | SimpleAudioPlayerPlaybackStore | Provides externally managed playback snapshots for a synced audio shell. Advanced integration prop. | | activePlaylistItem | PlaylistItem \| null | Controlled active playlist item for external shells. | | playlistItems | PlaylistItem[] | Controlled playlist items for external shells. | | externalTranscriptState | TranscriptStateSnapshot \| null | Controlled transcript state for external shells. | | embedCompact | boolean | Compact embedded-audio layout hint. Mostly used by the iframe/web-component host flow. | | isEmbeddedPlayer | boolean | Tells the audio player it is running inside an embedded surface. Advanced host integration prop. | | embedOverlayExpanded | boolean | Controls whether the embedded audio overlay is expanded. Mostly for host/web-component synchronization. | | bottomFixed | boolean | Pins the audio shell to the bottom of the viewport. Useful for persistent audio bars. | | bottomWidth | boolean | When bottom-fixed, expands the shell to the full viewport width. | | forceExpanded | boolean | Forces the audio shell into its expanded presentation. | | disableExpandedFullscreen | boolean | Prevents the expanded audio shell from requesting browser fullscreen where supported. | | onEmbedOverlayToggle | (expanded: boolean) => void | Called when the embedded audio overlay expands or collapses. Advanced embed coordination prop. |

Static viewer React props

These are accepted by HyperstreamStaticMediaViewer.

| Prop | Type | How to use it | | --- | --- | --- | | source | StaticViewerSource | Required resolved static-media source. Use resolveStaticViewerSource(...) for the safest construction path. | | brandColor | string | Accent color for the static viewer chrome. | | showTitle | boolean | Shows or hides the title area. Defaults to true. | | showFullscreen | boolean | Shows or hides the fullscreen button. Defaults to true. | | showPageNavigation | boolean | Shows or hides the document page-navigation UI. Defaults to true. Document-only. | | showZoom | boolean | Shows or hides the zoom controls. Defaults to true. | | allowDownload | boolean | Shows a document download button and allows local download. Defaults to false. Document-only. | | viewerProtection | boolean | Enables the static viewer protection layer. Defaults to true. | | protectionLevel | "basic" \| "medium" \| "aggressive" | Protection intensity for protected static content. Defaults to medium. | | onViewerEvent | (type: string, payload?: Record<string, unknown>) => void | Receives static-viewer lifecycle and interaction events. | | channelId | string | Optional host channel identifier. Included on static-media analytics events when provided. | | studentId | string | Optional host student identifier. Included on static-media analytics events when provided. | | connectionType | string \| null | Advanced analytics/device hint override. | | isEmbed | boolean | Advanced host integration flag for embed surfaces. | | isMobile | boolean | Advanced mobile-layout override. | | lowPowerMode | boolean | Advanced analytics/device hint override. |

Helper example:

import {
  HyperstreamStaticMediaViewer,
  type StaticMediaPayload,
  resolveStaticViewerSource,
} from "@hyperstream/player";

const payload: StaticMediaPayload = {
  url: "https://example.com/assets/guide.pdf",
  media_type: "document",
  fileName: "Guide.pdf",
};

const source = resolveStaticViewerSource(payload, "DOCUMENT");

return source ? <HyperstreamStaticMediaViewer source={source} /> : null;

React data shapes

playlist

type PlaylistConfig = {
  title?: string;
  items: PlaylistItem[];
};

type PlaylistItem = {
  id: string;
  shortId?: string;
  title: string;
  artist?: string;
  description?: string;
  thumbnail?: string;
  brandColor?: string;
  watermark?: string;
  chapters?: { id?: number; title: string; startTime: number }[];
  duration?: number;
  url: string;
  signature?: string;
  ivhex?: string;
  transcripts?: { language: string; url: string }[];
};

Example:

<HyperstreamVideoPlayer
  title="Product Training"
  playlist={{
    title: "Onboarding Series",
    items: [
      {
        id: "intro",
        title: "Introduction",
        url: "https://example.com/video/intro.m3u8",
        thumbnail: "https://example.com/images/intro.jpg",
      },
      {
        id: "setup",
        title: "Setup",
        url: "https://example.com/video/setup.m3u8",
      },
    ],
  }}
/>

folderItem

folderItem is an advanced input for pre-fetched folder content. It is only honored when folderApi is true.

type FolderItemInput = {
  content_id?: string;
  short_id?: string;
  url?: string;
  signature?: string | null;
  ivhex?: string | null;
  fileName?: string;
  description?: string;
  thumbnail?: string | null;
  thumbnail_name?: string | null;
  preview_image?: string | null;
  media_type?: string | null;
  brand?: {
    name?: string;
    config?: {
      primary_color?: string;
      secondary_color?: string;
      text_color?: string;
    };
    watermark?: string | { url?: string } | null;
  };
  metaData?: {
    authors?: ({ name?: string } | string)[];
    chapters?: {
      name?: string;
      from_time?: number;
      to_time?: number;
      description?: string;
      thumbnail?: string;
    }[];
    transcripts?: { language?: string; url?: string }[];
  };
};

Example:

<HyperstreamAudioPlayer
  folderApi
  folderItem={{
    content_id: "episode-12",
    media_type: "audio",
    url: "https://dev-storage.fahs.io/media/audio/example/master.m3u8",
    fileName: "Episode 12",
    thumbnail: "https://dev-storage.fahs.io/media/thumbnail/example.jpg",
    brand: {
      config: { primary_color: "#0F766E" },
    },
  }}
/>

React callback payloads

Use these callbacks when the player needs to feed external UI, analytics, or host chrome.

| Callback | Payload summary | | --- | --- | | onPlaybackStateChange | { currentTime, duration, progress, isPlaying, isMuted, volume, playbackRate, isBuffering } | | onAssetAuthChange | { signature, ivhex } for protected assets | | onTranscriptStateChange | Transcript rows, available languages, and active language | | onDockStateChange | Dock open state, active tab, tab definitions, chapters, transcript rows, playlist rows, current time, active row id, and transcript language state | | onAccessDenied | { message, status } where status is currently used for HTTP 403 handling |

React ref API

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

export default function PlayerControls() {
  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>
    </>
  );
}

| Ref method | Returns | What it does | | --- | --- | --- | | play() | Promise<void> | Starts playback. Rejects if the browser blocks the play request. | | pause() | void | Pauses playback. | | seek(time) | void | Seeks to a time in seconds. | | setVolume(volume) | void | Sets volume on a 0-1 scale. | | setPlaybackRate(rate) | void | Sets the playback rate. | | setMuted(muted) | void | Explicitly mutes or unmutes playback. | | getCurrentTime() | number | Returns the current playback time in seconds. | | getDuration() | number | Returns the total duration in seconds. | | getHlsInstance() | any \| null | Returns the underlying HLS.js instance for advanced custom integrations. | | nextTrack() | void | Plays the next playlist item if one exists. | | prevTrack() | void | Plays the previous playlist item if one exists. | | selectPlaylistItem(item) | void | Loads a specific playlist item object. | | playItemById(id) | void | Loads a playlist item by id. | | closeDock() | void | Closes the dock panel. | | setDockTab(tab) | void | Switches the dock to A (chapters), B (transcript), or C (playlist). | | setActiveCaption(language) | void | Switches the active caption or transcript language. |

Web Component API

The standalone script renders the player inside a /watch iframe and forwards a small imperative API and event bridge onto the custom element.

HTML attributes

Use these on <hyperstream-player>.

| Attribute | Values | How to use it | | --- | --- | --- | | src | string | Main Hyperstream or FAHS URL. | | q | string | Short slug. The embed route resolves it into a playable Hyperstream URL. | | direct-src | string | Direct media file or HLS URL that bypasses Hyperstream resolution. | | title | string | Primary title shown by the player. | | artist | string | Secondary label shown by the player. | | thumbnail | string | Thumbnail or artwork image URL. | | poster | string | Poster image URL. | | brand-color | string | Main accent color. | | primary-color | string | Legacy accent-color alias. brand-color takes precedence when both are present. | | secondary-color | string | Additional brand color forwarded to the embed route. | | text-color | string | Text-color override forwarded to the embed route. | | skin | string | Player skin name. Use audio skins for audio mode and default or minimalist for video mode. | | mode | audio, video, image, or document | Forces the initial media mode when the source itself does not make that obvious. | | media-type | audio, video, image, or document | Explicit media-type override. Prefer this when you know the embed should render as static media. | | controls | true or false | Enables the player controls. | | show-controls | true or false | Shows or hides the player control chrome. | | show-fullscreen | true or false | Shows or hides the static-viewer fullscreen button. Document and image modes only. | | show-page-navigation | true or false | Shows or hides the static-viewer page-navigation UI. Document mode only. | | show-title | true or false | Shows or hides the title area. | | show-zoom | true or false | Shows or hides the static-viewer zoom controls. Document and image modes only. | | autoplay | true or false | Attempts autoplay. Browsers may still block unmuted autoplay. | | muted | true or false | Starts muted. | | mute-on-start | true or false | Forces the initial play attempt to start muted. | | initial-volume | number | Initial volume. 0-100 is recommended. | | playback-speed | number | Initial playback speed. | | loop | true or false | Loops the current item. | | object-fit | contain, cover, fill, none, scale-down | Controls stage fitting. | | aspect-ratio | 16:9, 9:16, 1:1, 1.777, and similar | Forces the player aspect ratio. | | max-stage-height | CSS length | Caps the stage height, for example 70vh. | | bottom-fixed | true or false | Audio-mode layout option that pins the audio shell to the bottom. | | bottom-width | true or false | Audio-mode layout option that expands bottom-fixed audio to full viewport width. | | api-key | string | API key for protected content. | | channel-id | string | Optional host channel identifier. Included on every player analytics event payload when provided. | | student-id | string | Optional host student identifier. Included on every player analytics event payload when provided. | | folder-api | true or false | Enables property-based folder item delivery through element.folderItem. | | overlay-color | dark or light | Chooses the overlay treatment used for titles and controls. | | viewer-protection | true or false | Enables the static-viewer protection layer. Static-media modes only. | | protection-level | basic, medium, or aggressive | Protection intensity for protected static content. Static-media modes only. | | allow-download | true or false | Enables local document download from the static viewer. Defaults to false. Document mode only. |

Web component properties

These are JavaScript properties on the custom element, not HTML attributes.

| Property | Type | How to use it | | --- | --- | --- | | channelId | string | Programmatic equivalent of the channel-id attribute. | | studentId | string | Programmatic equivalent of the student-id attribute. | | folderApi | boolean | Programmatic equivalent of the folder-api attribute. | | folderItem | FolderItemInput \| null | Supplies a folder item object to the iframe player. Use this with folderApi = true. |

Example:

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

<hyperstream-player id="folder-player" folder-api="true" mode="audio"></hyperstream-player>

<script>
  const player = document.getElementById("folder-player");

  player.folderItem = {
    content_id: "episode-12",
    media_type: "audio",
    url: "https://dev-storage.fahs.io/media/audio/example/master.m3u8",
    fileName: "Episode 12",
    thumbnail: "https://dev-storage.fahs.io/media/thumbnail/example.jpg",
    brand: {
      config: { primary_color: "#0F766E" },
    },
  };
</script>

Web component methods

Command methods are fire-and-forget. Getter methods return promises because the element bridges commands into the iframe and waits for a response.

| Method | Returns | What it does | | --- | --- | --- | | play() | void | Starts playback. | | pause() | void | Pauses playback. | | seek(time) | void | Seeks to a time in seconds. | | seekTo(time) | void | Alias for seek() using the explicit seek-to bridge message. | | setVolume(volume) | void | Sets the volume on a 0-1 scale. | | setPlaybackRate(rate) | void | Sets the playback rate. | | setMuted(muted) | void | Explicitly mutes or unmutes playback. | | mute() | void | Shortcut for setMuted(true). | | unmute() | void | Shortcut for setMuted(false). | | playItem(id) | void | Plays a playlist item by id. | | setLanguage(language) | void | Switches the active caption or transcript language. | | closeDock() | void | Closes the dock panel. | | getDuration() | Promise<number> | Resolves to the total duration in seconds. | | getCurrentTime() | Promise<number> | Resolves to the current playback time in seconds. | | getVolume() | Promise<number> | Resolves to the current volume on a 0-1 scale. | | getMuted() | Promise<boolean> | Resolves to whether playback is muted. | | getPaused() | Promise<boolean> | Resolves to whether playback is paused. | | getPlaybackRate() | Promise<number> | Resolves to the current playback rate. | | destroy() | void | Fully tears down the iframe, dock bridge, and pending requests. Useful in SPA environments when removing the element manually. |

Example:

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

  player.play();
  player.seek(30);
  player.setVolume(0.8);

  player.getCurrentTime().then((value) => {
    console.log("Current time", value);
  });
</script>

Web component events

The custom element forwards standard playback events as bubbling CustomEvents.

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

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

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

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

  player.addEventListener("mediatypedetected", (event) => {
    console.log(event.detail.mediaType);
  });
<\/script>

| Event | event.detail | What it means | | --- | --- | --- | | ready | undefined | The iframe player is attached and ready to receive commands. | | play | undefined | Playback started. | | pause | undefined | Playback paused. | | ended | undefined | Playback reached the end. | | timeupdate | { currentTime, duration } | The playback position changed. | | volumechange | { volume, muted } | Volume or mute state changed. | | ratechange | { rate } | Playback speed changed. | | mediatypedetected | { mediaType: "AUDIO" \| "VIDEO" } | The underlying content resolved to audio or video. | | error | implementation-defined error payload | The embedded player reported an error. |

Common Recipes

Protected content with an API key

React:

<HyperstreamVideoPlayer
  hyperstreamUrl="https://dev.fahs.io/abc123"
  apiKey="your-api-key"
  title="Private Training"
/>

Web component:

<hyperstream-player
  src="https://dev.fahs.io/abc123"
  api-key="your-api-key"
  title="Private Training"
></hyperstream-player>

Bottom-fixed audio bar

React:

<HyperstreamAudioPlayer
  directSrc="https://example.com/audio/show.mp3"
  title="Daily Briefing"
  bottomFixed
  bottomWidth
  skin="bar"
/>

Web component:

<hyperstream-player
  mode="audio"
  direct-src="https://example.com/audio/show.mp3"
  title="Daily Briefing"
  skin="bar"
  bottom-fixed="true"
  bottom-width="true"
></hyperstream-player>

Force audio mode for ambiguous sources

<hyperstream-player
  src="https://dev.fahs.io/some-slug"
  mode="audio"
  skin="glass"
></hyperstream-player>

Troubleshooting

The React player looks unstyled

Import the stylesheet once:

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

Autoplay is blocked

Browsers usually block autoplay with sound. Use muteOnStart or set the player muted at startup.

The web component is visible, but no media plays

Check these first:

1. The source is reachable.
2. If the source is protected, the correct api-key is provided.
3. If you are using folder mode, folder-api is enabled and element.folderItem has a valid url.

Chapters, transcript, or playlist are missing

Those panels only appear when the source actually provides that metadata or when you pass a playlist directly in React.

License

MIT