MediaService
katanakit-js / MediaService
Class: MediaService
Section titled “Class: MediaService”Defined in: core/services/media.service.ts:36
MediaService — Singleton facade over media source parsing and embed markup generation (YouTube, Vimeo and direct video files).
Applies the Singleton pattern (one shared instance via MediaService.getInstance) and the Facade pattern: each public method hides the provider-specific parsing and HTML details behind one call. Everything is pure string building — no DOM, no fetch — so the instance is safe to share across environments (Node, Bun, browser, SSR).
Every public method uses the use* prefix per CONTRIBUTING.md; the module
level use* functions below are thin wrappers kept for call-site ergonomics.
Example
Section titled “Example”import { useBuildVideoEmbed } from "katanakit-js";
const { html } = useBuildVideoEmbed({ src: "https://youtu.be/…", title: "My talk",});Methods
Section titled “Methods”useBuildVideoEmbed()
Section titled “useBuildVideoEmbed()”useBuildVideoEmbed(options): { id: string; provider: "unknown" | "file" | "youtube" | "vimeo"; raw: string;} & { html: string;};Defined in: core/services/media.service.ts:248
Builds the semantically correct embed HTML for any supported source.
- Direct files (
.mp4/.webm) →<figure><video controls …>(native). - YouTube / Vimeo →
<figure><iframe …>(embedded context), or a click-to-play facade (<button>+ thumbnail) whenfacade: trueso.md/.mdxposts never pay the iframe cost on load.
Pure string builder: SSR-safe, no DOM access. Escape is applied to all interpolated attributes.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
options |
{ aspect?: string; caption?: string; className?: string; facade?: boolean; poster?: string; src: string; title: string; youtube?: { autoplay?: boolean; end?: number; params?: Record<string, string | number | boolean>; start?: number; }; } |
Source + a11y + presentation options. |
options.aspect? |
string |
Aspect ratio box: 16/9 (default) or 4/3, 1/1, 9/16. |
options.caption? |
string |
Optional <figcaption> text. |
options.className? |
string |
Extra CSS class on the <figure> wrapper. |
options.facade? |
boolean |
Render the click-to-play facade for embeds (no heavy iframe on load). |
options.poster? |
string |
Poster for native <video> or facade thumbnail override. |
options.src? |
string |
YouTube URL/id, Vimeo URL/id, or direct .mp4/.webm URL. |
options.title? |
string |
Accessible title. Used as <iframe title> / <video aria-label>. |
options.youtube? |
{ autoplay?: boolean; end?: number; params?: Record<string, string | number | boolean>; start?: number; } |
YouTube player options (only for youtube provider). |
options.youtube.autoplay? |
boolean |
Autoplay on iframe creation (facade clicks pass 1). |
options.youtube.end? |
number |
End time in seconds. |
options.youtube.params? |
Record<string, string | number | boolean> |
Extra playerVars merged into the query string. |
options.youtube.start? |
number |
Start time in seconds. |
Returns
Section titled “Returns”{
id: string;
provider: "unknown" | "file" | "youtube" | "vimeo";
raw: string;
} & {
html: string;
}
{ provider, id, html } with the ready-to-inject markup.
Example
Section titled “Example”const { html } = useBuildVideoEmbed({ src: "https://youtu.be/…", title: "My talk",});useBuildVimeoEmbedUrl()
Section titled “useBuildVimeoEmbedUrl()”useBuildVimeoEmbedUrl(videoId): string;Defined in: core/services/media.service.ts:195
Builds the Vimeo player embed URL with privacy defaults.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
videoId |
string |
Numeric Vimeo video id. |
Returns
Section titled “Returns”string
Player URL ready for <iframe src>.
useBuildYoutubeEmbedUrl()
Section titled “useBuildYoutubeEmbedUrl()”useBuildYoutubeEmbedUrl(videoId, options?): string;Defined in: core/services/media.service.ts:174
Builds the privacy-enhanced YouTube embed URL (youtube-nocookie).
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
videoId |
string |
11-char YouTube video id. |
options? |
{ autoplay?: boolean; end?: number; params?: Record<string, string | number | boolean>; start?: number; } |
Player options (start/end/autoplay/extra params). |
options.autoplay? |
boolean |
Autoplay on iframe creation (facade clicks pass 1). |
options.end? |
number |
End time in seconds. |
options.params? |
Record<string, string | number | boolean> |
Extra playerVars merged into the query string. |
options.start? |
number |
Start time in seconds. |
Returns
Section titled “Returns”string
Embed URL ready for <iframe src>.
useBuildYoutubeThumbnail()
Section titled “useBuildYoutubeThumbnail()”useBuildYoutubeThumbnail(videoId, quality?): string;Defined in: core/services/media.service.ts:208
Builds the public YouTube thumbnail URL (no API key needed).
Parameters
Section titled “Parameters”| Parameter | Type | Default value | Description |
|---|---|---|---|
videoId |
string |
undefined |
11-char YouTube video id. |
quality? |
"default" | "mqdefault" | "hqdefault" | "sddefault" | "maxresdefault" |
"hqdefault" |
Thumbnail quality (defaults to hqdefault). |
Returns
Section titled “Returns”string
Thumbnail image URL.
useGetVimeoVideoId()
Section titled “useGetVimeoVideoId()”useGetVimeoVideoId(input): string | null;Defined in: core/services/media.service.ts:129
Extracts a Vimeo video id from a URL or bare numeric id.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
input |
string |
URL or bare numeric id. |
Returns
Section titled “Returns”string | null
The numeric id or null.
useGetYoutubeVideoId()
Section titled “useGetYoutubeVideoId()”useGetYoutubeVideoId(input): string | null;Defined in: core/services/media.service.ts:89
Extracts a YouTube video id from a watch / shorts / live / embed /
youtu.be URL or a bare 11-char id. Returns null when not matched.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
input |
string |
URL or bare video id. |
Returns
Section titled “Returns”string | null
The 11-char video id or null.
Example
Section titled “Example”useGetYoutubeVideoId("https://www.youtube.com/watch?v=dQw4w9WgXcQ"); // "dQw4w9WgXcQ"useGetYoutubeVideoId("https://youtu.be/dQw4w9WgXcQ"); // "dQw4w9WgXcQ"useGetYoutubeVideoId("dQw4w9WgXcQ"); // "dQw4w9WgXcQ"useParseMediaSource()
Section titled “useParseMediaSource()”useParseMediaSource(input): { id: string; provider: "unknown" | "file" | "youtube" | "vimeo"; raw: string;};Defined in: core/services/media.service.ts:156
Normalizes any supported input into a MediaSource. Pure and SSR-safe: no DOM, no fetch.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
input |
string |
YouTube/Vimeo URL or id, or direct video file URL. |
Returns
Section titled “Returns”Normalized { provider, id, raw }.
id: string;Video id for youtube/vimeo, full URL for file.
provider
Section titled “provider”provider: "unknown" | "file" | "youtube" | "vimeo" = MediaProviderSchema;raw: string;Original input (URL or bare id).
Example
Section titled “Example”useParseMediaSource("https://youtu.be/dQw4w9WgXcQ");// { provider: "youtube", id: "dQw4w9WgXcQ", raw: "…" }useParseSmartVideoOptions()
Section titled “useParseSmartVideoOptions()”useParseSmartVideoOptions(input): FetchResult<{ aspect?: string; caption?: string; className?: string; facade?: boolean; poster?: string; src: string; title: string; youtube?: { autoplay?: boolean; end?: number; params?: Record<string, string | number | boolean>; start?: number; };}>;Defined in: core/services/media.service.ts:225
Validates unknown input (parsed JSON, frontmatter, CMS payloads) against
the SmartVideoOptions schema. Returns a Safe Result instead of throwing.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
input |
unknown |
Unknown value to validate. |
Returns
Section titled “Returns”FetchResult<{
aspect?: string;
caption?: string;
className?: string;
facade?: boolean;
poster?: string;
src: string;
title: string;
youtube?: {
autoplay?: boolean;
end?: number;
params?: Record<string, string | number | boolean>;
start?: number;
};
}>
FetchResult<SmartVideoOptions> with typed options or a Validation Error.
Example
Section titled “Example”const result = useParseSmartVideoOptions(JSON.parse(raw));if (result.ok) useBuildVideoEmbed(result.data);getInstance()
Section titled “getInstance()”static getInstance(): MediaService;Defined in: core/services/media.service.ts:43
Returns the shared instance (Singleton).
Returns
Section titled “Returns”MediaService