Kappapps SDK

Appearance

Class: MediaService ​

Service for playing the channel's media (sounds, videos, images) on the overlay, and for managing the media library (listing, fetching, and uploading files).

Remarks ​

Available everywhere via k.medias. You never have to instantiate this service yourself — it is created by the SDK when the app/widget starts up.

The play* methods return a media object you can then act on (stop it, set its volume, reposition it).

Example ​

ts
// Play a sound from the channel's library
const media = await k.medias.get('applause');
if (media) {
    await k.medias.playMedia({ file: media, volume: 70, position: { x: 0, y: 0, w: 1920, h: 1080 }, timeline: {} });
}

// Play a sound from a URL with an effect
await k.medias.playAudio('https://example.com/boom.mp3', 80, ['echo']);

Implements ​

Properties ​

audioContext ​

ts
audioContext: AudioContext;

Web Audio context shared by the sounds and videos of this app instance only.

Methods ​

all() ​

ts
all(): Promise<ChannelMediaFileData[]>;

Lists every media file in the channel's library.

Returns ​

Promise<ChannelMediaFileData[]>

The array of available media items (ChannelMediaFileData).

See ​

get to fetch a specific media item.

get() ​

ts
get(name): Promise<ChannelMediaFileData>;

Fetches a media file from the channel's library by its name.

Parameters ​

name ​

string

Name of the media to look up.

Returns ​

Promise<ChannelMediaFileData>

The media's metadata (ChannelMediaFileData), or null if it does not exist.

Example ​

ts
const file = await k.medias.get('intro');
if (file) {
    await k.medias.playMedia({ file, volume: 50, position: { x: 0, y: 0, w: 1920, h: 1080 }, timeline: {} });
}

See ​

all to list every media item.

getLibrary() ​

ts
getLibrary(slug): Promise<LibraryMediaFileData>;

Fetches an asset of the public Kappapps media library by its slug.

Parameters ​

slug ​

string

Stable identifier of the asset (e.g. kapp-ding).

Returns ​

Promise<LibraryMediaFileData>

The asset's metadata (LibraryMediaFileData), or null if no published asset matches this slug.

Example ​

ts
const file = await k.medias.getLibrary('kapp-ding');
if (file) {
    await k.medias.playMedia({ file, volume: 60, position: { x: 0, y: 0, w: 1920, h: 1080 }, timeline: {} });
}

library() ​

ts
library(): Promise<LibraryMediaFileData[]>;

Lists every asset of the public Kappapps media library — ready-to-use sounds, images and videos curated by the Kappapps team, playable on any channel without any upload.

Returns ​

Promise<LibraryMediaFileData[]>

The array of published library assets (LibraryMediaFileData).

Example ​

ts
const assets = await k.medias.library();
const sounds = assets.filter(a => a.type === 'sounds');

See ​

getLibrary to fetch a specific asset by slug.

playAudio() ​

ts
playAudio(
   source, 
   volume?, 
effects?): Promise<KAudio>;

Plays a sound from a URL or a prepared GeneratedAudio result. Prepared audio bypasses normalization and additional effects; volume still applies.

Parameters ​

source ​

| string | GeneratedAudio

URL of the audio file, or the complete result of textToSpeech.generate().

volume? ​

number = 50

Playback volume, from 0 to 100.

effects? ​

KAudioEffect[] = []

Audio effects to apply (see KAudioEffect).

Returns ​

Promise<KAudio>

The KAudio currently playing.

Default Value ​

50

Default Value ​

[]

Example ​

ts
await k.medias.playAudio('https://example.com/laugh.mp3', 70, ['radio']);

playClip() ​

ts
playClip(source, options?): Promise<MediaPlayback>;

Plays one image, sound or video using composition loops/animations and an explicit finish promise.

Parameters ​

source ​

| ChannelMediaFileData | CompositionSource

options? ​

Partial<Omit<Clip, "id" | "source" | "fileId">> = {}

Returns ​

Promise<MediaPlayback>

playComposition() ​

ts
playComposition(composition): Promise<MediaPlayback>;

Plays a versioned composition. Resolves at startup; await playback.finished for the natural end or a voluntary stop. Existing playMedia keeps its contract.

Parameters ​

composition ​

CompositionV1

Returns ​

Promise<MediaPlayback>

playImage() ​

ts
playImage(source, position?): Promise<KImage>;

Displays an image from a URL, at a given position on screen.

Parameters ​

source ​

string

URL of the image file to display.

position? ​

MediaPositionCreate = {}

Position and size on screen (see MediaPositionCreate).

Returns ​

Promise<KImage>

The KImage that is displayed.

Default Value ​

{} (fullscreen)

Example ​

ts
const img = await k.medias.playImage('https://example.com/badge.png', { x: 1600, y: 50, w: 256, h: 256 });
setTimeout(() => img.remove(), 3000);

playLibrary() ​

ts
playLibrary(slug, options?): Promise<KMedia>;

Plays an asset of the public Kappapps media library by its slug.

Parameters ​

slug ​

string

Stable identifier of the asset (e.g. kapp-ding).

options? ​

MediaCreateOptions = {}

Playback settings (volume, position, effects, timeline) — see MediaCreateOptions.

Returns ​

Promise<KMedia>

The KMedia currently playing, or null if no published asset matches this slug.

Default Value ​

{}

Example ​

ts
await k.medias.playLibrary('kapp-ding', { volume: 70 });

playMedia() ​

ts
playMedia(media, options?): Promise<KMedia>;

Plays a media item from the channel's library (sound, video, or image depending on its type).

Parameters ​

media ​

MediaData

The media to play (MediaData), typically obtained via get.

options? ​

MediaCreateOptions = {}

Playback settings (volume, position, effects, timeline) — see MediaCreateOptions. Missing fields fall back to the media's own values.

Returns ​

Promise<KMedia>

The KMedia currently playing, which you can then act on (stop, setVolume, setPosition…).

Default Value ​

{}

Example ​

ts
const file = await k.medias.get('victory');
if (file) {
    const media = await k.medias.playMedia({ file, volume: 60, position: { x: 0, y: 0, w: 1920, h: 1080 }, timeline: {} });
    setTimeout(() => media.stop(), 5000);
}

See ​

playAudio, playVideo, playImage

playVideo() ​

ts
playVideo(
   source, 
   volume?, 
position?): Promise<KVideo>;

Plays a video from a URL, at a given volume and position on screen.

Parameters ​

source ​

string

URL of the video file to play.

volume? ​

number = 50

Playback volume, from 0 to 100.

position? ​

MediaPositionCreate = {}

Position and size on screen (see MediaPositionCreate).

Returns ​

Promise<KVideo>

The KVideo currently playing.

Default Value ​

50

Default Value ​

{} (fullscreen)

Example ​

ts
await k.medias.playVideo('https://example.com/intro.mp4', 80, { x: 100, y: 100, w: 640, h: 360 });

upload() ​

ts
upload(blob, name?): Promise<ChannelMediaFileData>;

Uploads a new file to the channel's media library.

Parameters ​

blob ​

Blob

Binary contents of the file to upload.

name? ​

string = null

Display name to preserve for the media (surrounding whitespace is trimmed). If omitted or null, the backend generates a unique name for this upload.

Returns ​

Promise<ChannelMediaFileData>

The metadata of the created media (ChannelMediaFileData).

Default Value ​

null

Remarks ​

Explicit names can be shared by several files; use distinct names for unambiguous get lookups. Names must be nonblank, at most 255 characters, without path separators or control characters.