Integrationsleitfaden für den Freecaster Player

Willkommen! Dieser Leitfaden zeigt dir, wie du den Freecaster Video Player auf deiner Website einbettest und mit einfachem HTML und JavaScript anpasst.

Zielgruppe

Diese Dokumentation richtet sich an Frontend-Entwickler, die mit HTML, CSS und JavaScript vertraut sind.

Statistiken & DSGVO-Konformität

Achtung! Standardmäßig erfasst der Player keine Statistiken. Um Statistikmodule (wie Google Analytics, Mux, Youbora etc.) zu aktivieren, musst du das Attribut stats auf true setzen (siehe Konfiguration). Denk daran, dass das Einholen einer Einwilligung der Nutzer gemäß DSGVO verpflichtend ist.
Die besten Integrationspraktiken findest du hier.

Erste Schritte: Player einbetten

Es gibt zwei Möglichkeiten, den Player einzubetten. Wir empfehlen die JavaScript-Integration, da sie einen einfacheren Zugriff auf die Player-API bietet und mehr Flexibilität für CSS-Anpassungen.

JavaScript-Einbindung (empfohlen)Iframe-Einbindung

Player-Skript einbinden: Füge dieses Script-Tag in deine Seite ein (idealerweise im <head> oder vor dem schließenden </body>-Tag). Du benötigst es nur einmal, auch wenn du mehrere Player einsetzt.
```
<script async src="https://player.freecaster.com/freecaster/stable/fcplayer.js"></script>
```

Player-Platzhalter hinzufügen: Füge ein <div> an der Stelle ein, an der der Player angezeigt werden soll. Verwende die Klasse freecaster-player und das Attribut data-video-id mit der Video-ID. Das Skript ersetzt dieses div automatisch durch den Player.

<!-- Einfaches Beispiel -->
<div class="freecaster-player" data-video-id="YOUR_VIDEO_ID"></div>

<!-- Beispiel mit Anpassungen -->
<div class="freecaster-player" 
     data-video-id="YOUR_VIDEO_ID" 
     data-width="640" 
     data-autoplay="true" 
     data-muted="true" 
     data-lang="fr-be" 
     data-stats="true">
</div>

Bette ein <iframe> mit folgender URL-Struktur ein: https://player.freecaster.com/embed/VIDEO_ID.html. Füge Konfigurationsoptionen als Query-Parameter hinzu.

<!-- Responsiver Iframe-Wrapper -->
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
    <iframe 
        src="https://player.freecaster.com/embed/YOUR_VIDEO_ID.html?width=640&autoplay=true&muted=true&stats=true&lang=fr-be" 
        style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: 0;" 
        frameborder="0" 
        scrolling="no" 
        allowfullscreen>
    </iframe>
</div>

Hinweis: Der div-Wrapper sorgt für ein responsives Iframe (16:9-Seitenverhältnis). Passe padding-bottom für andere Seitenverhältnisse an.

Testumgebung

Verwende bei Tests in unserer Validierungsumgebung player.freecaster-uat.com anstelle von player.freecaster.com in den URLs.

Wesentliche HTML-Konfiguration

Damit der Player ordnungsgemäß funktioniert, insbesondere in Bezug auf Responsive-Funktionen und die Anzeige von Sonderzeichen, stelle sicher, dass diese <meta>-Tags im <head> deines HTML-Dokuments vorhanden sind:

<head>
  <meta charset="UTF-8"> 
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <!-- Weitere Head-Elemente -->
</head>

charset="UTF-8": Verhindert Probleme mit der Zeichenkodierung, etwa falsch angezeigte Sonderzeichen.
viewport: Sorgt dafür, dass der Player auf unterschiedlichen Geräten korrekt skaliert.

Player konfigurieren

Du kannst Verhalten und Darstellung des Players über Attribute anpassen.

JavaScript-Einbindung: Nutze data-*-Attribute am <div> (z. B. data-autoplay="true").
Iframe-Einbindung: Hänge Query-Parameter an die src-URL an (z. B. ?autoplay=true).

Namenskonvention für Attribute

Für Iframe-Query-Parameter wird camelCase statt Bindestrichen verwendet.

JS Embed: data-my-attribute="value"
Iframe Embed: ?myAttribute=value

Hier sind die verfügbaren Konfigurationsoptionen:

Attribute (`data-*`) / Parameter (`?param=`)	erwarteter Wert	Standard	Beschreibung
`audio_only`	boolean	`false`	Blendet videospezifische UI-Elemente aus und bietet eine auf Audio ausgerichtete Nutzererfahrung. Siehe Hinweis unten.
`autopause`	boolean	`true`	Pausiert die Wiedergabe automatisch, wenn der Player aus dem sichtbaren Bereich (Viewport) scrollt.
`autoplay`	boolean	`false`	Startet die Wiedergabe automatisch. Erfordert `muted=true` in den meisten modernen Browsern. Siehe Googles Autoplay-Richtlinie.
`cast`	boolean	`false`	Aktiviert Chromecast- / AirPlay-Buttons.
`chapters.enabled` / `chaptersEnabled`	boolean	`false`	Aktiviert die Kapitel-Funktion.
`chapters.list` / `chaptersList`	`[]<Chapter>` (JSON)	`[]`	Stellt die Kapitel-Daten bereit. Siehe Hinweis unten zum Format.
`chapters.style` / `chaptersStyle`	`hidden`, `dot`, `full_width`	`hidden`	Steuert, wie Kapitelmarken in der Timeline angezeigt werden.
`controls`	boolean	`true`	Blendet die Steuerleiste des Players ein oder aus.
`float_on_scroll` / `floatOnScroll`	boolean	`false`	Zeigt einen Mini-Player an, der am Viewport klebt, wenn der Hauptplayer aus dem sichtbaren Bereich scrollt.
`height`	number		Legt die Höhe des Players in Pixeln fest (z. B. `360`). Verwende `100%` zusammen mit `width="100%"` für `stretching`.
`lang`	`language-country`		Legt die UI-Sprache des Players fest (z. B. `en-us`, `fr-be`). Folgt RFC 5646.
`loop`	boolean	`false`	Startet die Video-Wiedergabe nach dem Ende automatisch neu.
`multiplay`	boolean	`false`	Gibt an, ob dieser Player weiter lesen soll, wenn ein anderer Player auf derselben Seite mit der Wiedergabe beginnt. Nützlich bei mehreren Playern pro Seite.
`muted`	boolean	`false`	Schaltet den Ton des Players standardmäßig stumm. Erforderlich, damit Autoplay zuverlässig funktioniert.
`noads`	boolean	`false`	Deaktiviert Werbung.
`poster`	Bild-URL (string)		Gibt die URL eines benutzerdefinierten Posterbildes an, das vor dem Start der Wiedergabe angezeigt werden soll.
`preload`	`auto`, `metadata`, `none`	`auto`	Legt fest, wie das Video vorgeladen wird: `auto` (lädt Videodaten), `metadata` (nur Metadaten wie Dauer, Größe), `none` (kein Preload). Siehe Abschnitt Mehrere Player.
`speed.labels` / `speedLabels`	string		Komma-separierte Beschriftungen für Geschwindigkeitsoptionen (z. B. `"Slow,Normal,Fast"`). Muss der Anzahl in `speed.options` entsprechen.
`speed.options` / `speedOptions`	string	`"0.2,0.5,1,2,10"`	Lesegeschwindigkeiten, durch ein Komma getrennt (z. B. `"0.5,1,1.5,2"`).
`stats`	boolean	`false`	Wichtig: Aktiviert sämtliches Tracking und alle Statistikmodule (Google Analytics, Mux, Youbora etc.). Erfordert Einwilligung der Nutzer (DSGVO).
`stretching`	`fill`, `cover`, `none`	`none`	Skalierungsmodus für Video und Titelbild (Poster), um die Abmessungen des Players anzupassen. Erfordert `width="100%"` und `height="100%"`. `fill`: Staucht/zieht, ignoriert Seitenverhältnis. `cover`: Zoomt/schneidet zu, behält Seitenverhältnis bei. `none`: Originalgröße (evtl. schwarze Balken).
`subtitles.default_lang` / `subtitlesDefaultLang`	`lang` (ISO 639-1)		Legt die beim Start aktive Untertitelspur über ihren zweibuchstabigen Sprachcode fest (z. B. `en`, `fr`).
`subtitles.lang` / `subtitlesLang`	`lang` (ISO 639-1)		Filtert das Untertitel-Menü, sodass nur die angegebene Sprache angezeigt wird (z. B. `es`).
`subtitles.native` / `subtitlesNative`	boolean	`false`	Verwendet das native Untertitel-Rendering des Browsers (unterstützt VTT-Styling).
`thumbnails.src` / `thumbnailsSrc`	Thumbnails-URL		URL für die Vorschau-Thumbnails der Timeline (VTT-Format).
`trackers.ga.enabled` / `trackersGaEnabled`	boolean	`false`	Aktiviert speziell Google Analytics 4 (GA4) Tracking. Erfordert `stats=true`. Events werden an `window.dataLayer` gesendet.
`trackers.ga.tag_ids` / `trackersGaTagIds`	string		Komma-separierte Liste von GA4 Measurement IDs (z. B. `"G-XXXXXXXXXX,G-YYYYYYYYYY"`), an die Events gesendet werden sollen.
`volume`	number (0.0 bis 1.0)	`1`	Legt das anfängliche Volumen fest (0 = Lautlos, 1 = Maximalvolumen). Wenn der Benutzer den Ton manuell ausschaltet, wird diese Auswahl bei nachfolgenden Ladevorgängen beibehalten. Die Richtlinien für das automatische Lesen des Browsers können diese Einstellung beeinflussen.
`watermark.enabled` / `watermarkEnabled`	boolean	`false`	Blendet das Wasserzeichen ein oder aus.
`width`	number		Legt die Breite des Players in Pixeln fest (z. B. `640`). Verwende `100%` zusammen mit `height="100%"` für `stretching`.

Hinweise

dnt veraltet

Das alte Attribut dnt ist veraltet. Bitte verwende der Klarheit halber stats. dnt wird aus Gründen der Rückwärtskompatibilität beibehalten.

Verwendung von audio_only

Wenn du Audio-Inhalte einbindest und kein Poster-Bild anzeigen möchtest, setze audio_only auf true für eine minimalistische UI.

Kapitel-Liste (chapters.list)

Verwende ein JSON-Array von Kapitelobjekten:

[
  {
    "id": "chapter-1-unique-id", 
    "start": 0,         // Startzeit in Millisekunden
    "end": 15000,       // Endzeit in Millisekunden
    "title": "Einführung",
    "description": "Überblick über das Thema",
    "customData": { "key": "value" } // Optional: eigene Metadaten
  },
  {
    "id": "chapter-2-unique-id",
    "start": 15000,
    "end": 45000,
    "title": "Vertiefung" 
  }
]

start und end sind in Millisekunden.
customData wird in kapitelbezogenen Events durchgereicht.

Kapitel-Events

Bei Verwendung von Kapiteln gibt der Player Events aus, die du abfangen kannst (siehe Player Instance API und Events):

fc_chapter_user_enter: Der Nutzer betritt den Zeitbereich eines Kapitels.
fc_chapter_user_leave: Der Nutzer verlässt den Zeitbereich eines Kapitels.

fc_chapter_user_mark: Wird zum Startzeitpunkt jedes Kapitels ausgelöst.

Beispiel mit der Player-API:

playerInstance.on('fc_chapter_user_enter', (payload) => {
  console.log(`Kapitel betreten: ${payload.data.title}`);
  console.log('Custom-Daten:', payload.data.customData); 
});

Player-Instanzen abrufen

Verwendung von window.fcplayer

Du kannst die globale Funktion window.fcplayer() verwenden, um Referenzen auf aktive fcplayer-Instanzen in deiner Anwendung zu erhalten.

Funktionsweise:

Das Verhalten hängt davon ab, ob du eine ID übergibst:

Erste Instanz abrufen: Wenn du die Funktion ohne Argument (window.fcplayer()) aufrufst, gibt sie die erste auf der Seite erstellte fcplayer-Instanz zurück. Existiert noch kein Player, wird null zurückgegeben.
Nach ID abrufen: Wenn du eine string-ID übergibst (window.fcplayer('mySpecificPlayerId')), sucht die Funktion nach der Instanz mit dieser ID. Wird sie gefunden, wird sie zurückgegeben, ansonsten null.

Parameter:

playerId (String | undefined):
- Optional. Die ID der gewünschten Player-Instanz.
- Wenn weggelassen, wird die erste verfügbare Instanz zurückgegeben.

Rückgabe:

Ein fcplayer-Objekt, wenn eine Instanz gefunden wird (oder die erste Instanz existiert).
null, wenn keine Instanz existiert oder die angegebene ID unbekannt ist.

Beispiele:

// Szenario 1: Es wird nur ein Player erwartet oder du benötigst den Standard-Player
const player = window.fcplayer();
if (player) {
  console.log('Player gefunden:', player.id);
} else {
  console.error('Keine fcplayer-Instanzen gefunden!');
}

// Szenario 2: Einen bestimmten Player unter mehreren steuern
const bannerPlayer = window.fcplayer('promo-video-player');
if (bannerPlayer) {
  bannerPlayer.mute();
} else {
  console.log('Promo-Player nicht bereit oder existiert nicht.');
}

Verwendung des Player-Callbacks

Das Array window._fcpr bietet einen Mechanismus, um Code auszuführen, sobald eine fcplayer-Instanz initialisiert wurde. Du fügst dem Array Callback-Funktionen hinzu.

Setup:

Stelle sicher, dass das Array initialisiert ist, idealerweise früh in der Seitenausführung:

window._fcpr = window._fcpr || [];

Verwendung:

Füge eine Funktion hinzu, die als Argument eine Player-Instanz erhält. Diese Funktion wird für alle bestehenden Instanzen ausgeführt sowie für alle zukünftigen Instanzen, sobald sie erstellt werden.

window._fcpr.push(playerInstance => {
  // Code, der für jede Player-Instanz ausgeführt wird
  console.log('Player erkannt:', playerInstance.id);
  // Beispiel: Error-Listener hinzufügen
  playerInstance.on('error', (err) => {
    console.error(`Player ${playerInstance.id} Fehler:`, err);
  });
});

Beispiel: Autoplay bei Sichtbarkeit

Dieses Beispiel zeigt das automatische Starten der Wiedergabe über das viewenter-Event, das nur einmal pro Player ausgelöst wird.

Beispiel:

// Dieses Skript einmalig auf der Seite einbinden
window._fcpr = window._fcpr || [];
window._fcpr.push(playerInstance => {
  // Video nur beim ersten Sichtbarwerden abspielen
  playerInstance.once('viewenter', () => {
    // togglePlay(true) oder play() - togglePlay vermeidet Fehler, falls die Wiedergabe bereits läuft
    playerInstance.togglePlay(true); 
    console.log(`Player ${playerInstance.id || ''} ist sichtbar und wird abgespielt.`);
  });
});

Du kannst Links erstellen, die die Wiedergabe zu bestimmten Zeitpunkten starten (und optional stoppen), indem du die Query-Parameter start_time und end_time verwendest. Die Werte sind in Sekunden.

Beispiel: https://player.freecaster.com/embed/VIDEO_ID.html?start_time=120&end_time=300

Dieser Link startet das Video bei 2 Minuten (120 s) und pausiert es automatisch bei 5 Minuten (300 s).

Einschränkung

Diese Funktionalität gilt nur für Video on Demand (VOD), nicht für Livestreams.

Aktuelle Zeit abrufen

Die aktuelle Wiedergabezeit in Sekunden kannst du mit der Player-API erhalten: playerInstance.currentTime.

Player-Instanz-API (nur JavaScript-Einbindung)

Um den Player programmatisch zu steuern (Abspielen, Pausieren, Seek, Events, …), benötigst du die Player-Instanz. Diese ist nur bei Verwendung der JavaScript-Einbindung verfügbar.

Iframe-Einschränkung

Bei der Iframe-Einbindung kannst du nicht direkt auf die Player-Instanz oder ihre API zugreifen.

So erhältst du die Player-Instanz:

Über eine Element-ID: Vergib ein eindeutiges id-Attribut für dein Player-<div>.

<div id="my-player" class="freecaster-player" data-video-id="VIDEO_ID"></div>

Verwende anschließend die globale Funktion fcplayer():

// Warten, bis das Player-Skript geladen und der Player initialisiert ist
document.addEventListener('DOMContentLoaded', () => {
  const playerInstance = fcplayer('my-player');
  if (playerInstance) {
    playerInstance.play(); 
  }
});

Über den Callback window._fcpr: Dieses Array erhält eine Callback-Funktion für jede Player-Instanz, die erstellt wird. Praktisch, wenn du die ID nicht kennst oder mehrere Player verwaltest.

window._fcpr = window._fcpr || [];

window._fcpr.push((playerInstance) => {
  console.log(`Player bereit: ${playerInstance.id || 'Keine ID'}`);

  // Beispiel: Listener nur für einen speziellen Player
  if (playerInstance.id === 'my-special-player') {
    playerInstance.on('play', () => console.log('Special Player gestartet!'));
  }

  // Beispiel: Listener für ALLE Player
  playerInstance.on('error', (err) => console.error(`Player-Fehler:`, err));
});

Alle Instanzen abrufen: Du kannst jederzeit ein Array aller initialisierten Player-Instanzen erhalten:

const allPlayers = window.fcplayers();

Mehrere Player auf einer Seite verwenden

Wenn mehrere Player gleichzeitig sichtbar sind, kann das Standardverhalten des Browsers (insbesondere mit preload="auto" oder autoplay="true") zu hoher Bandbreitennutzung und schlechter Performance führen, da mehrere Videos parallel laden.

Empfehlung:

Setze preload="none" und autoplay="false" für deine Player-divs.
Verwende die Player-API, um nur dann zu starten, wenn der Player in den Viewport kommt.
Stelle sicher, dass data-multiplay nicht auf true gesetzt ist. Andernfalls pausieren andere Player nicht automatisch, wenn einer von ihnen startet.

Beispiel:

<!-- Player 1 -->
<div class="freecaster-player"
     data-video-id="VIDEO_ID_1"
     data-multiplay="false"       // Du kannst dieses Feld auch weglassen, wenn es `false` bleiben soll
     data-preload="none"
     data-muted="true" 
     data-autoplay="false">
</div> 

<!-- Player 2 -->
<div class="freecaster-player"
     data-video-id="VIDEO_ID_2"
     data-multiplay="true"
     data-preload="none"
     data-muted="true"
     data-autoplay="false">
</div>

// Dieses Skript einmalig auf der Seite einfügen
window._fcpr = window._fcpr || [];
window._fcpr.push(playerInstance => {
  // Wiedergabe nur bei erstmaligem Eintritt in den Viewport starten
  playerInstance.once('viewenter', () => {
    playerInstance.togglePlay(true); 
    console.log(`Player ${playerInstance.id || ''} ist sichtbar und wird abgespielt.`);
  });

  // Optional: Beim Verlassen des Viewports pausieren (wenn `autopause` nicht verwendet wird)
  // playerInstance.on('viewleave', () => {
  //   playerInstance.pause();
  //   console.log(`Player ${playerInstance.id || ''} ist außer Sicht und wurde pausiert.`);
  // });
});

Diese Vorgehensweise ermöglicht ein „autoplay-ähnliches“ Erlebnis, ohne den Browser beim Laden der Seite zu überlasten.

Player-Eigenschaften (API)

Auf folgende Eigenschaften kannst du über eine Player-Instanz zugreifen:

Eigenschaft	Beschreibung	Beispiel	Rückgabetyp	Beispielwert
`audioTracks`	Liste verfügbarer Audiotracks. Siehe MDN	`player.audioTracks`	AudioTrackList	`AudioTrackList {length: 2, 0: AudioTrack, 1: AudioTrack}`
`blackBarsHeight`	Gibt die Gesamthöhe in Pixeln der schwarzen Streifen (falls vorhanden) zurück, die durch eine Abweichung zwischen den Containermaßen und dem Videoverhältnis entstehen.	`player.blackBarsHeight`	number	`100` (falls Balken vorhanden) / `0` (falls nicht)
`config`	Das aktuelle Konfigurationsobjekt des Players.	`player.config`	object	`{ autoplay: false, muted: true, ... }`
`container`	Das zentrale `HTMLElement` des Players.	`player.container`	HTMLElement	`<div class="freecaster-player...">`
`controlbar`	Das `HTMLElement` der Player-Steuerleiste.	`player.controlbar`	HTMLElement	`<div class="fp-controls...">`
`currentAudioTrack`	Aktiver/aktuell wiedergegebener Audiotrack oder `null`.	`player.currentAudioTrack`	AudioTrack \| null	`AudioTrack {id: 'en', ...}` / `null`
`currentTime`	Aktuelle Wiedergabezeit in Sekunden.	`player.currentTime`	number	`123.456`
`currentTimecode`	Aktuelle Wiedergabezeit als Timecode-String (HH:MM:SS:FF oder HH:MM:SS.ms).	`player.currentTimecode`	string	`"00:02:03:15"` oder `"00:02:03.500"`
`currentTimestamp`	Aktuelle Wiedergabezeit als UTC-Timestamp in Millisekunden (nur Live DASH/HLS, besondere Konfiguration nötig).	`player.currentTimestamp`	number \| null	`1678886400123`
`duration`	Gesamtdauer des Videos in Sekunden. Für Livestreams `Infinity`.	`player.duration`	number	`600.5` oder `Infinity`
`id`	Der `id`-Wert des Player-Containers, falls gesetzt.	`player.id`	string \| null	`"my-player"`
`live`	Gibt an, ob es sich um einen Livestream handelt.	`player.live`	boolean	`true` / `false`
`muted`	Gibt an, ob der Player aktuell stummgeschaltet ist.	`player.muted`	boolean	`true` / `false`
`paused`	Gibt an, ob die Wiedergabe gerade pausiert ist.	`player.paused`	boolean	`true` / `false`
`subtitlesEnabled`	Gibt an, ob Untertitel/Captions aktuell aktiviert sind.	`player.subtitlesEnabled`	boolean	`true` / `false`
`version`	Versionsstring des Players.	`player.version`	string	`"freecaster-player x.y.z (core v...)"`
`volume`	Aktuelle Lautstärke (0.0 bis 1.0).	`player.volume`	number	`0.75`

Veraltete Eigenschaften

Diese Attribute/Eigenschaften sind veraltet. Verwende stattdessen die in der Konfigurationstabelle genannten Alternativen.

Veraltet	Stattdessen verwenden
`mute`	`muted` (Attribut)
`repeat`	`loop` (Attribut)
`aspectratio`	Über CSS/Container lösen
`playbackRateControls`	`speed.options` etc.
`localization`	`lang` (Attribut)
`displaytitle`	(kein direktes Äquivalent)
`displaydescription`	(kein direktes Äquivalent)
`fc-token`	`data-video-id`
`locale`	`lang` (Attribut)
`dnt`	`stats` (Attribut)

Player-Methoden (API)

Diese Methoden kannst du auf einer Player-Instanz aufrufen:

Methode	Beschreibung	Beispiel
`play()`	Startet oder setzt die Wiedergabe fort.	`player.play()`
`pause()`	Pausiert die Wiedergabe.	`player.pause()`
`togglePlay(force?)`	Schaltet zwischen Play und Pause um. Optionaler boolescher Parameter erzwingt den Zustand.	`player.togglePlay()` `player.togglePlay(true)`
`seek(time)`	Springt zu einer bestimmten Zeit (Sekunden) oder einem Timestamp (Millisekunden).	`player.seek(120)` (2 Minuten) `player.seek(1678886400123)` (Timestamp, falls unterstützt)
`setSrc(source)`	Lädt eine neue Videoquelle. Siehe die Anmerkung unten für das Format.	`player.setSrc('new_video.mp4')` `player.setSrc({ type: 'application/dash+xml', src: 'manifest.mpd' })`
`loadVideo(videoId)`	Lädt ein neues Video anhand der Freecaster-Video-ID und ersetzt das aktuelle.	`player.loadVideo('NEW_VIDEO_ID')`
`destroy()`	Entfernt die Player-Instanz und die zugehörigen DOM-Elemente.	`player.destroy()`
`toggleFullScreen()`	Wechselt den Vollbildmodus ein/aus.	`player.toggleFullScreen()`
`setConfig(key, value)`	Aktualisiert Konfigurationsoptionen nach der Initialisierung.	`player.setConfig('volume', 0.5)` `player.setConfig({ controls: false, loop: true })`
`goBackToLive()`	Springt bei Live-Streams mit DVR an die aktuelle Live-Position.	`player.goBackToLive()`
`mute(shouldMute)`	Schaltet den Player stumm (`true`) oder stellt den Ton wieder her (`false`).	`player.mute(true)`
`setVolume(level)`	Setzt die Lautstärke (0.0 bis 1.0).	`player.setVolume(0.8)`
`on(event, callback)`	Registriert einen Event-Listener.	`player.on('play', () => console.log('Wiedergabe gestartet'))`
`off(event, callback)`	Entfernt einen Event-Listener.	`player.off('play', myPlayHandler)`
`once(event, callback)`	Registriert einen Event-Listener, der genau einmal ausgeführt wird.	`player.once('ended', () => console.log('Video beendet'))`

seek() mit Timestamps

Die Verwendung eines absoluten Timestamps (Millisekunden) mit seek() erfordert:

Live: Der Timestamp muss innerhalb des verfügbaren DVR-Fensters liegen.
VOD: Die Eigenschaft player.config.start (normalerweise durch die API bereitgestellt) muss gesetzt sein, damit der Player den Timestamp auf einen Video-Offset abbilden kann.

Format für setSrc()

Der Parameter source für setSrc() kann sein:

Ein einfacher URL-String: 'https://path/to/video.mp4'
Ein Source-Objekt: { type: 'application/dash+xml', src: 'https://path/to/manifest.mpd' }
Ein Array von Source-Objekten (der Player wählt die erste kompatible Quelle):

[
  { type: 'application/x-mpegurl', src: 'https://path/to/playlist.m3u8' },
  { type: 'video/mp4', src: 'https://path/to/fallback.mp4' }
]

Integration von Google Analytics (GA4)

So sendest du Player-Events an Google Analytics 4:

Google-Tag einbinden: Stelle sicher, dass das Standard-Google-Tag gtag.js auf deiner Seite vorhanden ist. (Siehe Google-Dokumentation)
Stats aktivieren: Setze das Attribut data-stats="true" auf deinem Player-div.
GA-Tracker aktivieren: Setze data-trackers.ga.enabled="true".
(Optional) Tag-IDs angeben: Falls nötig, gib deine GA4 Measurement IDs über data-trackers.ga.tag_ids="G-XXXXXXXXXX,G-YYYYYYYYYY" an. Wenn weggelassen, werden Events ggf. an global konfigurierte Tags gesendet (gtag('config', 'GA_MEASUREMENT_ID')).

<!-- Stelle sicher, dass das GA-Skript auf der Seite geladen wird -->

<div class="freecaster-player" 
     data-video-id="YOUR_VIDEO_ID"
     data-stats="true"  
     data-trackers.ga.enabled="true" 
     data-trackers.ga.tag_ids="G-XXXXXXXXXX"> 
</div>

Player-Events (play, pause, seek, ended, error etc.) werden automatisch in window.dataLayer geschrieben.

Events

Du kannst verschiedene Events auf der Player-Instanz mit player.on('eventName', callback) abonnieren.

Standard-HTML-Media-Events

Dies sind gängige Events des HTML5-Videoelements.

Event	Beschreibung
`play`	Wird ausgelöst, wenn die Wiedergabe beginnt oder fortgesetzt wird.
`pause`	Wird ausgelöst, wenn die Wiedergabe pausiert wird.
`ended`	Wird ausgelöst, wenn das Ende des Mediums erreicht ist.
`error`	Wird ausgelöst, wenn beim Laden oder Abspielen ein Fehler auftritt.
`seeking`	Wird ausgelöst, wenn eine Such-/Seek-Operation startet.
`seeked`	Wird ausgelöst, wenn eine Such-/Seek-Operation abgeschlossen ist.
`timeupdate`	Wird regelmäßig während der Änderung von `currentTime` ausgelöst (sparsam verwenden).
`volumechange`	Wird ausgelöst, wenn Lautstärke oder Mute-Status geändert werden.
`ratechange`	Wird ausgelöst, wenn die Wiedergabegeschwindigkeit geändert wird.
`waiting`	Wird ausgelöst, wenn die Wiedergabe aufgrund von Buffering stoppt.
`playing`	Wird ausgelöst, wenn die Wiedergabe nach Buffering oder Seeking fortgesetzt wird.
`loadstart`	Wird ausgelöst, wenn der Browser beginnt, Metadaten zu laden.
`loadedmetadata`	Wird ausgelöst, wenn Metadaten (Dauer, Dimensionen usw.) geladen wurden.
`loadeddata`	Wird ausgelöst, wenn der erste Frame bereitsteht.
`canplay`	Wird ausgelöst, wenn die Wiedergabe starten könnte, aber ggf. noch puffern muss.
`canplaythrough`	Wird ausgelöst, wenn der Player schätzt, dass das Medium bis zum Ende ohne weiteres Puffern abgespielt werden kann.
`resize`	Wird ausgelöst, wenn sich die Abmessungen des Players ändern.

Freecaster-spezifische Events

Diese Events sind spezifisch für den Freecaster Player.

Event	Beschreibung	Beispiel-Payload
`fullscreenenter`	Wird ausgelöst, wenn der Player in den Vollbildmodus wechselt.	-
`fullscreenexit`	Wird ausgelöst, wenn der Player den Vollbildmodus verlässt.	-
`viewenter`	Wird ausgelöst, wenn der Player in den sichtbaren Bereich des Viewports scrollt.	-
`viewleave`	Wird ausgelöst, wenn der Player den sichtbaren Bereich des Viewports verlässt.	-
`fcplayerDestroy`	Wird kurz vor der vollständigen Zerstörung der Player-Instanz ausgelöst.	-
`fcplayerSrcChanged`	Wird ausgelöst, nachdem die Quelle via `setSrc` oder `loadVideo` geändert wurde.	`{ src: 'new_source_url_or_object' }`
`fcplayerConfigChanged`	Wird ausgelöst, nachdem Konfigurationseinstellungen über `setConfig` geändert wurden.	`{ key: 'config_key', value: 'new_value' }` oder `{ changes: { key1: value1, ... } }`
`fc_chapter_user_enter`	Wird ausgelöst, wenn die Wiedergabe in den Zeitbereich eines Kapitels läuft.	`{ data: ChapterObject }`
`fc_chapter_user_leave`	Wird ausgelöst, wenn die Wiedergabe den Zeitbereich eines Kapitels verlässt.	`{ data: ChapterObject }`
`fc_chapter_user_mark`	Wird exakt zur `start`-Zeit eines Kapitels ausgelöst.	`{ data: ChapterObject }`
`fcplayerCountdownTick`	(falls vorhanden) Wird einmal pro Sekunde während eines Pre-Roll-Countdowns ausgelöst.	`{ remaining: number }` (Sekunden)
`fcplayerCountdownEnabled`	(falls vorhanden) Wird ausgelöst, wenn ein Countdown startet.	-
`fcplayerCountdownDisabled`	(falls vorhanden) Wird ausgelöst, wenn ein Countdown endet oder gestoppt wird.	-
`fcplayerCountdownZero`	(falls vorhanden) Wird ausgelöst, wenn der Countdown Null erreicht.	-

Beispiel-Listener:

playerInstance.on('viewenter', () => {
  console.log('Player ist jetzt sichtbar!');
});

playerInstance.on('fcplayerSrcChanged', (payload) => {
  console.log('Neue Quelle geladen:', payload.src);
});

playerInstance.on('fc_chapter_user_enter', (payload) => {
  console.log(`Kapitel betreten: ${payload.data.title}`);
});

Nur Audio (Audio Only)

Der Freecaster Player kann im Audio-Only-Modus betrieben werden – ideal für Podcasts, Musik oder MP3-Wiedergabe.

Aktivierung

Setze das Attribut audio_only auf true:

<!-- JavaScript-Einbindung -->
<div class="freecaster-player" 
     data-video-id="YOUR_AUDIO_ID" 
     data-audio_only="true"
     data-poster="cover.jpg"
     data-title="Artist Name"
     data-description="Track Title">
</div>

Verhalten im Audio-Only-Modus

Das Player-Design wechselt zu einem für Audio optimierten Layout.
Wenn ein Titelbild (poster) definiert ist, wird es angezeigt oberhalb der Fortschrittsanzeige (wie ein Albumcover).
Der Videotitel wird als Artist angezeigt.
Die Videobeschreibung wird als Track-Titel angezeigt.

Attribute setzen

Artist, Track-Titel und Poster können entweder per Dataset-Attribute / Iframe-Parameter gesetzt oder aus den Backend-Metadaten übernommen werden. Wenn sowohl Backend- als auch Dataset/Iframe-Werte existieren, haben Dataset/Iframe Vorrang.

Transkript-Unterstützung

Für Audio- oder Video-Assets kann im Backend eine Transkriptdatei hochgeladen werden. Ist diese vorhanden, erscheint das Transkript automatisch im Player.

Der Freecaster Player nutzt Cookies und HTML Local Storage für notwendige Funktionalität und – sofern aktiviert – für Statistiken. Drittanbieter-Dienste (z. B. Youbora), die mit dem Player integriert sind, verwenden diese Technologien ebenfalls.

Was sind Cookies & Local Storage?

Cookies: Kleine Dateien, die dein Browser speichert, z. B. zur Sitzungs- oder Präferenzverwaltung.
Local Storage: Webspeichermechanismus, mit dem Websites Daten dauerhaft im Browser ablegen können.

Nicht essenziellen Speicher deaktivieren

Du kannst verhindern, dass der Player statistikbezogene Cookies und Local-Storage-Einträge setzt, indem du das Attribut stats auf false setzt:

<div class="freecaster-player" data-video-id="YOUR_VIDEO_ID" data-stats="false"></div>

Dadurch wird das Statistik-Tracking deaktiviert, was jedoch unsere Möglichkeiten zur Analyse von Player-Performance und Fehlern einschränkt. Funktional notwendiger Speicher (wie to) wird weiterhin verwendet.

Verwendete Speicher-Einträge

Freecaster (notwendige Funktionalität)

Name	Speicher	Zweck	Ablauf
`to`	Local Storage	Speichert Daten für Zeitoffset-Berechnungen, um Countdowns für Live-Events korrekt darzustellen.	30 Minuten

Youbora (Statistiken – nur wenn `stats=true`)

Name	Speicher	Zweck	Ablauf
`youbora.accCode`	Local Storage	Speichert den Youbora-Accountcode.	Permanent
`youbora.data`	Local Storage	Cache für Youbora-API-Einstellungen.	Permanent
`youbora.dataTime`	Local Storage	Zeitstempel für den Cache der Einstellungen.	Permanent
`youbora.host`	Local Storage	Host-Endpunkt für das Senden der Youbora-Daten.	Permanent
`youbora.offlineViews`	Local Storage	Speichert ungesendete Statistik-Pings (offline).	Permanent
`youbora.session`	Local Storage	Eindeutige Kennung für die aktuelle Sitzung.	Permanent
`youbora.sessionExpire`	Local Storage	Ablaufzeitpunkt der Sitzungskennung.	Permanent
`youbora.youboraDeviceUUID`	Local Storage	Zufällig generierte Geräte-ID für Tracking.	Permanent

(Hinweis: „Permanent“ bedeutet, dass die Daten erhalten bleiben, bis sie vom Nutzer oder von der Website gelöscht werden.)

Um die DSGVO zu erfüllen, dürfen Player-Statistiken erst nach ausdrücklicher Einwilligung des Nutzers aktiviert werden.

Empfohlener Ablauf:

Einwilligung einholen: Zeige vor der Initialisierung des Players mit aktivierten Statistiken eine Consent-UI (z. B. Banner, Popup) an.
Entscheidung des Nutzers verarbeiten:
- Einwilligung erteilt: Markiere die Einwilligung (z. B. setze data-stats="true" am Player-Element).
- Einwilligung abgelehnt / noch keine Eingabe: Lass das Player-Element unverändert (füge data-stats="true" nicht hinzu).
Player initialisieren: Füge das <div class="freecaster-player"></div> in das Dokument ein; fcplayer.js initialisiert den Video-Player dann automatisch.