Array of all Episode objects in the feed

Most recently published episode (by release date)

Returns a random episode from the collection. If a random pool filter is set, it is applied first; if the filter yields no results, falls back to the full episode list.

Provide a callback to restrict which episodes are eligible for random selection. The callback receives the full episodes array and must return a filtered array. Pass null to clear the filter. Used by Radio Mode's auto-queue logic as well as direct calls to PodCube.random.

Full-text search across title, description, tags, model, origin, year, and date strings. Returns matching episodes.

Find episodes related to the given episode using weighted scoring: model matching (12 points exact, 4 points prefix), origin (10 points), locale (6), region (4), zone (2, but the value "USA" is explicitly excluded to prevent overly broad matches), shared tags (3 each), and same lore year (5). Planet is not scored. Minimum threshold: 7 points. Default limit is 10.

Returns array of episodes with lore dates closest to today's actual date (uses absolute day number calculation)

Returns episodes flagged with hasIssues=true (missing critical data: audio URL, duration, or lore date)

Robustly find an episode by ID with fuzzy matching. Handles URL drift between RSS and JSON feeds. Returns Episode object or null.

Array of unique model names (sorted alphabetically)

Array of unique origin points (sorted alphabetically)

Array of all unique tags across all episodes (sorted alphabetically)

Returns distribution object with counts for all metadata facets: { models: [{name, count}], origins: [], regions: [], zones: [], planets: [], locales: [], tags: [] }

Returns aggregate statistics: totalEpisodes, totalDuration, averageDuration, averageIntegrity, episodesWithDates, episodesWithAudio, episodesWithIntegrity, yearRange {min, max}, models count, origins count, types count

Group episodes into year eras using adaptive recursive subdivision algorithm. Threshold controls target episodes per group (default 5). Returns array of: { label, start, end, count, episodes }

Get the array index of an episode in the main episodes array (release order)

Get the next episode in release order. Returns null if at end.

Get the previous episode in release order. Returns null if at beginning.

Episodes sorted by publish date (newest first). Pass true for oldest first.

Episodes sorted by lore date (oldest first). Pass true for newest first. Automatically filters out episodes without dates.

Episodes sorted alphabetically by title. Pass true for reverse order.

Episodes sorted by duration (shortest first by default). Pass true for longest first.

Episodes sorted by integrity value (lowest first by default). Pass true for highest first.

Generic sort by any episode field. Example: sortBy('model', false)

Play a specific episode (adds to queue with playNow=true). If no episode provided, resumes current track. If queue is empty and Radio Mode is active, automatically picks a random track and plays it. If queue is empty and Radio Mode is off, this does nothing.

Pause playback

Toggle between play and pause states. Smart initialization: starts queue playback if no track is loaded but queue has items.

Skip to next track in queue. Respects stopAfterCurrent flag. Emits 'queueEnd' event when reaching end of queue.

Go to previous track in queue, or restart current track if >3 seconds in

Jump to specific time position in current track (clamped to 0)

Skip forward 20 seconds (configurable via CONFIG.SKIP_FORWARD)

Skip back 7 seconds (configurable via CONFIG.SKIP_BACK)

Set volume (0.0 to 1.0). Values are clamped to valid range. Returns clamped value.

Get current volume level (0.0 to 1.0)

Set playback speed (0.02 to 16.0). Returns true on success, false if out of range.

Get current playback rate (defaults to 1.0)

Set flag to stop playback after current track ends (soft stop)

Cancel the stop-after-current flag

Enable/disable Radio Mode. When enabled, automatically queues a random track when reaching the end of the queue, creating infinite playback. If enabled while the queue is empty or exhausted, immediately loads the next random track into position — but does not auto-play it (user must call play()). Respects any active random pool filter.

Add single episode or array of episodes to queue. If playNow=true, inserts after current and plays immediately. Queue has rotating buffer (max 400 items). Returns {count, queueLength}.

Insert episode immediately after current track (will play next). If nothing is playing, plays immediately.

Array of episodes currently in queue (read-only copy to prevent direct mutation)

Current position in queue (number). -1 if queue is empty.

Total duration of remaining queue in seconds. Includes remaining time of current track if playing.

Randomize queue order using Fisher-Yates algorithm. Keeps currently playing track at front (index 0).

Remove all tracks from queue, cancel preload, stop playback, clear session, remove audio src, and dismiss OS media session controls.

Remove specific track by index. Automatically adjusts queue index and loads new track if current was removed.

Move a track from one position to another in the queue. Automatically adjusts current index to maintain playback continuity.

Jump directly to a specific index in the queue and begin playback. Does nothing if the index is out of bounds.

Save array of episodes as a named playlist to localStorage. Returns playlist object with {name, created, episodes, totalDuration}.

Load playlist by name. Returns { name, created, episodes, totalDuration } or null if not found. Episodes are automatically rehydrated from current feed.

Get all saved playlists. Returns array of fully-loaded playlist objects, each with name, created timestamp, totalDuration, and rehydrated episode arrays.

Delete playlist by name. Returns true if deleted, false if not found.

Rename an existing playlist. Returns true on success, false if source playlist not found.

Load playlist and start playing immediately. Clears current queue. Returns true on success.

Add playlist episodes to queue without clearing or playing. Accepts playlist name (string) or playlist data object. Returns true on success.

Export playlist for sharing using Nano-GUID v7 compression (20-bit ID stream + plaintext title). Returns {name, episodes, code, totalDuration, url} or null on error.

Import a playlist from a share code. Returns {name, episodes, totalDuration, missingCount} or null if invalid. Uses fuzzy matching via nanoId.

Extract importPlaylist parameter from current URL, remove it from history, and return the code. Returns null if not found.

Currently playing Episode object, or null if nothing is playing. Returns episode at queueIndex.

Comprehensive playback status object with 30+ fields including: playing, loading, time, duration, remaining, percent, playbackRate, volume, episode info, queue state, buffer info, network state, system state, statistics, and formatted timestamps.

Boolean indicating if audio is currently loading

Boolean indicating if next track has been preloaded (triggered 5 seconds before current track ends)

Subscribe to event. Returns unsubscribe function. Available events: 'play', 'pause', 'track', 'ended', 'timeupdate', 'queue:changed', 'queueEnd', 'error'

Unsubscribe from event. If no callback provided, removes all listeners for that event.

Subscribe to event once, then automatically unsubscribe. Returns unsubscribe function.

Restore previous playback session from localStorage (async). Validates session structure, checks staleness (7 day max age), reconstructs queue, and resumes playback if needed. Returns true if session restored successfully.

Clean up all resources: clear session, stop playback, clear queue, remove all event listeners, and null audio elements.

Initialize/reinitialize the API (async). Pass true to force reload even if already initialized. Fetches feed, parses episodes, and sets ready state. Returns PodCube instance.

Switch between 'rss' and 'json' feed formats. Returns true on success. Must call init(true) after to reload feed.

Enable/disable debug logging to console. Persists to localStorage and reloads page after 500ms delay.

Current feed type ('rss' or 'json')

Current debug mode state (boolean)

Boolean — true once init() has completed successfully. False before initialization or if init threw an error.

Feed logo URL string extracted during init() (from the RSS <image> tag or JSON icon field). Null before initialization or if the feed provides no logo.

Reference to the Episode class itself. Useful for instanceof checks: ep instanceof PodCube.Episode.

Unique identifier (from feed GUID)

5-character hex string (20 bits) computed from the full episode GUID via FNV-1a hash. Used as the compressed identifier in playlist share codes.

Cleaned episode title (emoji removed, underscores converted to spaces)

Episode shortcode extracted from title before first underscore (e.g., "04.01.2050", "PC-042"), or null

Type: 'transmission' (🅿️), 'podcube_hq' (🔸), 'twibbie_ondemand' (💠), or 'none'

AI model name from metadata (e.g., "A65v.14", "Bird Mug"), or null

Origin point from metadata (e.g., "Dad's House", "Brad's House"), or null

Locale identifier from metadata, or null

Geographic region from metadata, or null

Geographic zone from metadata, or null

Planet name from metadata, or null

Composite location string: "origin, locale, region, zone, planet" (auto-generated, filters out null/empty values)

PodCubeDate object with lore date {year, month, day}, or "Unknown Date"

JavaScript Date object of publish date from feed

Distance from the episode's lore date to today. Returns "today" on an exact date match, a human-readable string otherwise (e.g., "2 years ago", "3 months from now", "500 years from now", "4 days ago"), or null if the episode has no lore date. Resolution cascades: years → months → weeks → days.

Raw integrity string from feed metadata (e.g., "94.7"). Never null — defaults to "0.0" for TWIBBIE/NONE episodes, or "0" for TRANSMISSION/HQ episodes without metadata. Described in-universe as a fake transmission quality percentage.

Numeric float parsed from integrity metadata. Never null — defaults to 0 if metadata is missing, invalid, or the episode type is TWIBBIE/NONE. No upper bound is enforced; value is whatever the feed provides.

Array of tag strings from metadata (comma-separated in feed), or empty array

Episode description HTML from feed (may contain metadata lines)

Direct URL to audio file from enclosure

Duration in seconds (parsed from various formats: "300", "05:00", "01:30:25")

Duration formatted as M:SS (e.g., "62:05"). Minutes are not zero-padded; seconds are. Returns "0:00" if duration is unavailable. Note: for HH:MM:SS formatting use status.durationFormatted instead.

Duration formatted with a randomly selected whimsical suffix. The format is M.FF<suffix> where M is whole minutes and FF is fractional minutes. Example outputs: "5.42ish minutes", "12.8 minutes (+/- a bit)", "30.5 or so minutes". Returns "IDK?" if duration is unavailable.

File size in bytes from enclosure length attribute, or null

Boolean - true if missing critical data (audioUrl, duration, or lore date)