Changeset 834bcc3 in Klonkt for src/assets/js/embed-player.js


Ignore:
Timestamp:
06/23/2026 06:14:27 PM (3 months ago)
Author:
Robin Genis <roboburr@…>
Branches:
main
Children:
d774679
Parents:
bb42dfb
Message:

i18n: translate Dutch code comments to English across src/

Comments in routes/services/views/config/middleware/assets translated to
English for the public repo. A few dev-facing throw/console message strings
were Englished too. No user-facing UI strings or i18n dictionary values changed
(src/services/i18n.js untouched). Logic unchanged.

Co-Authored-By: Claude <noreply@…>

File:
1 edited

Legend:

Unmodified
Added
Removed

  • src/assets/js/embed-player.js

    rbb42dfb r834bcc3  
    11/**
    2  * Klonkt Embed Player — eigen, in-huisstijl media-embeds bovenop de ÉCHTE
    3  * player-API's (YouTube IFrame API, SoundCloud Widget API, Spotify iFrame API).
     2 * Klonkt Embed Player — custom, on-brand media embeds on top of the REAL
     3 * player APIs (YouTube IFrame API, SoundCloud Widget API, Spotify iFrame API).
    44 *
    5  * De server (AudioEmbedService) rendert per embed een placeholder:
     5 * The server (AudioEmbedService) renders a placeholder per embed:
    66 *   <div class="folio-embed folio-embed--<provider> pcms-embed-card"
    77 *        data-embed-provider data-embed-ref data-embed-type data-embed-url></div>
    8  * Dit script bouwt daar onze eigen kaart omheen (cover/poster + onze play-knop +
    9  * voortgangsbalk in huisstijl) en bestuurt de onderliggende speler via de
    10  * platform-API, zodat play/pause/voortgang in ÓNZE handen liggen.
     8 * This script wraps it in our own card (cover/poster + our play button +
     9 * progress bar in brand style) and controls the underlying player via the
     10 * platform API, so play/pause/progress are in OUR hands.
    1111 *
    12  * Capability-eerlijkheid:
    13  *  - youtube/soundcloud  → volledig eigen controls (native chrome verborgen).
    14  *  - spotify             → besturing + onze frame eromheen; Spotify's eigen UI
    15  *                          blijft binnenin (kan niet anders zonder Premium+OAuth).
     12 * Capability honesty:
     13 *  - youtube/soundcloud  → fully custom controls (native chrome hidden).
     14 *  - spotify             → controls + our frame around it; Spotify's own UI
     15 *                          stays inside (no alternative without Premium+OAuth).
    1616 *
    17  * Mutual exclusion: elke speler (incl. de site-audiospeler in audio-player.js)
    18  * registreert zich in window.pcmsMediaRegistry. Start er één → de vorige pauzeert.
    19  * Dit vervangt de oude focus/blur-heuristiek door echte play-events.
     17 * Mutual exclusion: every player (incl. the site audio player in audio-player.js)
     18 * registers itself in window.pcmsMediaRegistry. Starting one pauses the previous.
     19 * This replaces the old focus/blur heuristic with real play events.
    2020 *
    21  * Singleton — guard tegen dubbel-init (HTMX laadt scripts soms opnieuw).
     21 * Singleton — guard against double-init (HTMX can reload scripts).
    2222 */
    2323(function () {
    … …  
    2525
    2626  // ============================================================
    27   // 0. Gedeelde playback-registry (ook door audio-player.js gebruikt)
     27  // 0. Shared playback registry (also used by audio-player.js)
    2828  // ============================================================
    2929  function registry() {
    … …  
    3131    const r = {
    3232      _active: null,
    33       // Markeer `player` als de enige actieve; pauzeer de vorige.
     33      // Mark `player` as the sole active one; pause the previous.
    3434      setActive(player) {
    3535        if (this._active && this._active !== player && this._active.pause) {
    … …  
    4545
    4646  // ============================================================
    47   // 1. Lazy script-loaders — 1 promise per platform, gedeeld over N embeds.
    48   //    We laden een platform-script PAS als er een embed van dat platform op de
    49   //    pagina daadwerkelijk wordt gestart.
     47  // 1. Lazy script loaders — 1 promise per platform, shared across N embeds.
     48  //    A platform script is only loaded when an embed from that platform
     49  //    is actually started on the page.
    5050  // ============================================================
    5151  const scripts = {};
    … …  
    5555      s.src = src; s.async = true;
    5656      s.onload = () => resolve();
    57       s.onerror = () => reject(new Error('embed-script faalde: ' + src));
     57      s.onerror = () => reject(new Error('embed script failed: ' + src));
    5858      document.head.appendChild(s);
    5959    });
    6060  }
    61   // Belangrijk: alle loaders REJECTEN bij een script-fout (bv. een ad-blocker die
    62   // het API-script blokkeert) én na een time-out — zodat de aanroeper netjes kan
    63   // terugvallen op het kale platform-iframe i.p.v. eeuwig te hangen.
     61  // Important: all loaders REJECT on script errors (e.g. an ad-blocker blocking
     62  // the API script) and on timeout — so the caller can gracefully fall back to
     63  // the plain platform iframe instead of hanging indefinitely.
    6464  const API_TIMEOUT = 8000;
    6565
    66   // YouTube: globale callback onYouTubeIframeAPIReady (1×) → in promise wikkelen.
     66  // YouTube: global callback onYouTubeIframeAPIReady (once) → wrap in a promise.
    6767  function ytApi() {
    6868    if (scripts.yt) return scripts.yt;
    … …  
    7979    return scripts.yt;
    8080  }
    81   // SoundCloud: geen globale ready-callback; resolve op script-onload, daarna
    82   // wacht elke widget op z'n eigen SC.Widget.Events.READY.
     81  // SoundCloud: no global ready callback; resolve on script onload, then
     82  // each widget waits for its own SC.Widget.Events.READY.
    8383  function scApi() {
    8484    if (scripts.sc) return scripts.sc;
    … …  
    9191    return scripts.sc;
    9292  }
    93   // Spotify: globale callback onSpotifyIframeApiReady(IFrameAPI) (1×) → wrappen.
     93  // Spotify: global callback onSpotifyIframeApiReady(IFrameAPI) (once) → wrap in a promise.
    9494  function spotifyApi() {
    9595    if (scripts.sp) return scripts.sp;
    … …  
    101101      };
    102102      loadScript('https://open.spotify.com/embed/iframe-api/v1').catch(reject);
    103       // Korter dan API_TIMEOUT: Spotify's bundle initialiseert snel óf helemaal
    104       // niet (CDN 503 / origin-gating). Niet 8s wachten vóór de iframe-fallback.
     103      // Shorter than API_TIMEOUT: Spotify's bundle initialises quickly or not at all
     104      // (CDN 503 / origin-gating). No need to wait 8 s before the iframe fallback.
    105105      setTimeout(() => reject(new Error('Spotify API timeout')), 4000);
    106106    });
    … …  
    108108  }
    109109
    110   // Kaal platform-iframe als fallback wanneer de JS-API geblokkeerd/onbereikbaar
    111   // is. Ad-blockers laten de embed-iframes doorgaans wél door. Autoplay-param
    112   // omdat we hier altijd in een user-gesture-context zitten (klik op play).
     110  // Plain platform iframe as fallback when the JS API is blocked/unreachable.
     111  // Ad-blockers generally let embed iframes through. Autoplay parameter
     112  // is safe here because we're always in a user-gesture context (play click).
    113113  function fallbackIframe(provider, ref, url) {
    114114    if (provider === 'youtube') {
    … …  
    138138    const m = (url || '').match(/(?:youtube\.com\/(?:watch\?(?:.*&)?v=|embed\/|shorts\/|live\/)|youtu\.be\/)([A-Za-z0-9_-]{11})/);
    139139    if (m) return m[1];
    140     return null;  // geen blinde slice — een ongeldige ref geeft liever niets dan een kapotte id
    141   }
    142   // Alleen http(s) als href toelaten (defense-in-depth tegen javascript:/data:).
     140    return null;  // no blind slice — an invalid ref returns nothing rather than a broken id
     141  }
     142  // Only allow http(s) as href (defense-in-depth against javascript:/data: URIs).
    143143  function safeHref(u) {
    144144    try { const p = new URL(u, location.href); return (p.protocol === 'http:' || p.protocol === 'https:') ? u : '#'; }
    … …  
    154154
    155155  // ============================================================
    156   // 3. Card controller — bouwt de huisstijl-kaart + delegeert naar een adapter
     156  // 3. Card controller — builds the on-brand card + delegates to an adapter
    157157  // ============================================================
    158158  function buildCard(el) {
    … …  
    165165    el.classList.remove('pcms-embed-loading');
    166166
    167     // Onze speler-zijde (registry-peer). pause() wijst naar de adapter zodra die
    168     // gemount is; ervoor is 't een no-op.
     167    // Our player side (registry peer). pause() points to the adapter once
     168    // mounted; before that it's a no-op.
    169169    let adapter = null;
    170170    const self = { pause() { if (adapter && adapter.pause) { try { adapter.pause(); } catch (e) {} } } };
    171171
    172     // Teardown-hook: aangeroepen door de MutationObserver als deze kaart uit de
    173     // DOM verdwijnt (HTMX-swap) → adapter opruimen (timers/iframes) + registry
    174     // vrijgeven, zodat er geen poll-timers of spelers blijven lekken.
     172    // Teardown hook: called by the MutationObserver when this card leaves the
     173    // DOM (HTMX swap) → clean up the adapter (timers/iframes) + release the registry,
     174    // so no poll timers or players keep leaking.
    175175    el._pcmsDestroy = function () {
    176176      try { if (adapter && adapter.destroy) adapter.destroy(); } catch (e) {}
    … …  
    182182    let dur = 0;
    183183
    184     // --- UI ophangen (verschilt per provider-type) ---
     184    // --- Mount the UI (differs per provider type) ---
    185185    const isVideo = provider === 'youtube';
    186186    const custom = provider === 'youtube' || provider === 'soundcloud'; // eigen controls
    … …  
    220220    const volEl = el.querySelector('.pcms-embed-vol');
    221221    const muteBtn = el.querySelector('.pcms-embed-mute');
    222     let vol = 100;       // huidige volume 0-100 (wordt op de adapter toegepast)
     222    let vol = 100;       // current volume 0-100 (applied to the adapter)
    223223    let preMuteVol = 100;
    224224
    … …  
    251251    };
    252252
    253     // API geblokkeerd/onbereikbaar → kaal platform-iframe (graceful degradation).
    254     // De mutual-exclusion loopt voor deze fallback via de blur-heuristiek
    255     // (audio-player.js), want de kaart krijgt geen .is-mounted.
     253    // API blocked/unreachable → plain platform iframe (graceful degradation).
     254    // Mutual exclusion for this fallback runs via the blur heuristic
     255    // (audio-player.js), because the card never gets .is-mounted.
    256256    function renderFallback() {
    257257      const fb = fallbackIframe(provider, ref, url);
    … …  
    271271      el.appendChild(iframe);
    272272
    273       // Mutual exclusion óók voor de fallback-iframe. Een cross-origin iframe
    274       // kunnen we niet via een API pauzeren, dus 'pauze' = herladen ZONDER
    275       // autoplay (= stopt het geluid, speler blijft zichtbaar/herstartbaar).
    276       // We registreren 'm als actief: nu (= gebruiker start de embed) pauzeert de
    277       // site-speler/andere embeds; en als de site-speler later start, pauzeert de
    278       // registry deze fallback.
     273      // Mutual exclusion also for the fallback iframe. A cross-origin iframe
     274      // cannot be paused via an API, so 'pause' = reload WITHOUT
     275      // autoplay (= stops the audio, player stays visible/restartable).
     276      // We register it as active: now (= user starts the embed) the
     277      // site player/other embeds pause; and when the site player starts later,
     278      // the registry pauses this fallback.
    279279      self.pause = function () {
    280280        try {
    … …  
    294294    }
    295295
    296     // Eerste interactie → adapter mounten + spelen. Daarna toggelt de knop.
     296    // First interaction → mount the adapter + play. The button toggles after that.
    297297    async function ensureMountedAndPlay() {
    298298      if (mounted) { if (adapter) adapter.play(); return; }
    299299      mounted = true;
    300       // Spotify: hun speler is toch niet te skinnen (besturing-only) én de
    301       // iFrame-API-bundle initialiseert in de praktijk vaak niet (CDN-gating/503)
    302       // → niet op de API wachten, meteen het kale Spotify-iframe tonen. Instant.
     300      // Spotify: their player cannot be skinned (controls-only) and the
     301      // iFrame API bundle often fails to initialise in practice (CDN-gating/503)
     302      // → don't wait for the API, show the plain Spotify iframe immediately.
    303303      if (provider === 'spotify') { renderFallback(); return; }
    304304      el.classList.add('pcms-embed-busy');
    … …  
    306306        adapter = await MOUNTERS[provider](mountEl, { ref, url }, hooks);
    307307        if (el._pcmsApplyVol) el._pcmsApplyVol();  // onthouden volume toepassen
    308         // is-mounted: CSS verbergt de poster (video) of de Spotify-facade en
    309         // toont de echte speler. Voor SoundCloud blijft onze kaart+balk staan en
    310         // blijft het (functionele) iframe off-screen verborgen.
     308        // is-mounted: CSS hides the poster (video) or Spotify facade and
     309        // shows the real player. For SoundCloud our card+bar stays visible and
     310        // the (functional) iframe remains hidden off-screen.
    311311        el.classList.add('is-mounted');
    312312        adapter.play();
    313313      } catch (err) {
    314         console.warn('[pcms-embed] API niet beschikbaar, val terug op kaal iframe', provider, err);
     314        console.warn('[pcms-embed] API unavailable, falling back to plain iframe', provider, err);
    315315        renderFallback();
    316316      }
    … …  
    328328      adapter.seek(ratio * dur);
    329329    });
    330     // Volume: schuif zet vol (0-100) en past 'm toe op de adapter (YT/SC hebben
    331     // setVolume). De waarde wordt onthouden en na het mounten opnieuw toegepast.
     330    // Volume: slider sets vol (0-100) and applies it to the adapter (YT/SC support
     331    // setVolume). The value is remembered and reapplied after mounting.
    332332    function applyVol() {
    333333      if (adapter && adapter.setVolume) { try { adapter.setVolume(vol); } catch (e) {} }
    … …  
    341341      applyVol();
    342342    });
    343     el._pcmsApplyVol = applyVol;  // door ensureMountedAndPlay aangeroepen na mount
     343    el._pcmsApplyVol = applyVol;  // called by ensureMountedAndPlay after mount
    344344  }
    345345
    … …  
    349349
    350350  // ============================================================
    351   // 4. Adapters — normaliseren de 3 zeer verschillende API's naar 1 vorm.
    352   //    Elke mounter geeft { play, pause, seek } terug en roept hooks aan met
    353   //    seconden (units worden hier rechtgetrokken).
     351  // 4. Adapters — normalise the 3 very different APIs to one common shape.
     352  //    Each mounter returns { play, pause, seek } and calls hooks with
     353  //    seconds (units are normalised here).
    354354  // ============================================================
    355355  const MOUNTERS = {
    … …  
    403403    },
    404404
    405     // ---- SoundCloud: Widget API, visual=false, eigen controls ----
     405    // ---- SoundCloud: Widget API, visual=false, custom controls ----
    406406    async soundcloud(mountEl, { ref, url }, hooks) {
    407407      const SC = await scApi();
    408       // Iframe zelf bouwen (kale balk) en daarna SC.Widget eraan hangen.
     408      // Build the iframe ourselves (bare bar) and then attach SC.Widget to it.
    409409      const iframe = document.createElement('iframe');
    410410      iframe.allow = 'autoplay';
    … …  
    453453    },
    454454
    455     // ---- Spotify: iFrame API — besturing + onze frame; geen eigen skin ----
     455    // ---- Spotify: iFrame API — controls + our frame; no custom skin ----
    456456    async spotify(mountEl, { ref, url }, hooks) {
    457457      const IFrameAPI = await spotifyApi();
    … …  
    473473            const d = e && e.data ? e.data : {};
    474474            hooks.onProgress((d.position || 0) / 1000, (d.duration || 0) / 1000);
    475             // Geen betrouwbare 'ended'-event bij Spotify; we behandelen elke
    476             // isPaused-overgang als play/pause. Einde = gewoon een pauze (de balk
    477             // blijft op de eindpositie i.p.v. misleidend naar 0 te springen).
     475            // No reliable 'ended' event from Spotify; we treat every
     476            // isPaused transition as play/pause. End = just a pause (the bar
     477            // stays at the end position rather than misleadingly jumping to 0).
    478478            if (d.isPaused === false && lastPaused) { lastPaused = false; hooks.onPlay(); }
    479479            else if (d.isPaused === true && !lastPaused) { lastPaused = true; hooks.onPause(); }
    … …  
    486486
    487487  // ============================================================
    488   // 5. Scan + HTMX-/DOM-mutatie-aware (de site navigeert deels via HTMX-swaps)
     488  // 5. Scan + HTMX/DOM-mutation-aware (the site partially navigates via HTMX swaps)
    489489  // ============================================================
    490490  function scan(root) {
    … …  
    492492      if (el.dataset.embedInit) return;
    493493      el.dataset.embedInit = '1';
    494       try { buildCard(el); } catch (e) { console.error('[pcms-embed] buildCard faalde', e); }
     494      try { buildCard(el); } catch (e) { console.error('[pcms-embed] buildCard failed', e); }
    495495    });
    496496  }
    … …  
    501501    scan(document);
    502502  }
    503   // HTMX vervangt #pcms-main bij interne navigatie → opnieuw scannen.
     503  // HTMX replaces #pcms-main on internal navigation → rescan.
    504504  document.body.addEventListener('htmx:afterSwap', (e) => scan(e.target || document));
    505505  document.body.addEventListener('htmx:load', (e) => scan(e.target || document));
    506506
    507   // Teardown bij verwijdering uit de DOM (HTMX vervangt #pcms-main innerHTML, of
    508   // een SPA-achtige swap). Zonder dit blijven YouTube-poll-timers + adapters/
    509   // iframes hangen als je wegnavigeert terwijl een embed speelt → CPU/geheugenlek
    510   // dat per navigatie opstapelt. We roepen el._pcmsDestroy() aan voor elke kaart
    511   // die echt uit het document verdwijnt.
     507  // Teardown on DOM removal (HTMX replaces #pcms-main innerHTML, or an SPA-like
     508  // swap). Without this, YouTube poll timers + adapters/iframes linger when
     509  // navigating away while an embed is playing → CPU/memory leak that accumulates
     510  // per navigation. We call el._pcmsDestroy() for every card that truly leaves the document.
    512511  const teardownObserver = new MutationObserver((muts) => {
    513512    for (const m of muts) {
Note: See TracChangeset for help on using the changeset viewer.