@anivire/twitch-embed-ts/dist/index.d.ts

Twitch Embed API Typescript wrapper

/**
 * Twitch embed options
 */
interface TwitchEmbedOptions {
    /**
     * Height of the embedded window, in pixels. Can be expressed as a percentage, by passing a string like `100%`. Recommended minimum: `300`
     */
    height: number | string;
    /**
     * Width of the embedded window, in pixels. Can be expressed as a percentage, by passing a string like `50%`. Recommended minimum: `400`
     */
    width: number | string;
    /**
     * Only required if your site is embedded on any domain(s) other than the one that instantiates the Twitch embed.
     *
     * Example parent parameter: `["streamernews.example.com", "embed.example.com"]`
     */
    parent?: string[];
    /**
     * Channel name (for a live stream).
     *
     * If channel is specified along with video and/or collection, only channel is used.
     *
     * To change the channel or video later, use `setChannel`, `setVideo`, or `setCollection`
     */
    channel?: string;
    /**
     * Video ID.
     *
     * If both video and collection are specified, the specified collection starts playing from the specified video.
     * If the video is not in the collection, collection is ignored and the specified video is played.
     *
     * To change the channel or video later, use `setChannel`, `setVideo`, or `setCollection`
     */
    video?: string;
    /**
     * Collection ID.
     *
     * If both video and collection are specified, the specified collection starts playing from the specified video.
     * If the video is not in the collection, collection is ignored and the specified video is played.
     *
     * To change the channel or video later, use `setChannel`, `setVideo`, or `setCollection`
     */
    collection?: string;
    /**
     * A boolean attribute set by inclusion. In other words, including the attribute enables fullscreen
     * viewing while excluding the attribute ensures fullscreen viewing is not allowed
     */
    allowfullscreen?: boolean;
    /**
     * If `true`, the video starts playing automatically, without the user clicking play.
     * The exception is mobile devices, on which video cannot be played without user interaction. Default: `true`
     */
    autoplay?: boolean;
    /**
     * Specifies whether the initial state of the video is muted. Default: `false`
     */
    muted?: boolean;
    /**
     * Determines the screen layout. Valid values:
     *
     * `video-with-chat`: default if channel is provided, and only supported for live content.
     * Shows both video and chat side-by-side. At narrow sizes, chat renders under the video player.
     *
     * `video`: default if channel is not provided. Shows only the video player (omits chat)
     */
    layout?: TwitchEmbedLayout;
    /**
     * The Twitch embed color theme to use. Valid values: `light` or `dark`. Default: `dark`
     */
    theme?: TwitchEmbedTheme;
    /**
     * Only valid for Video on Demand content. Time in the video where playback starts.
     * Specifies hours, minutes, and seconds. Default: 0h0m0s (the start of the video)
     */
    time?: string;
}
/**
 * Embed layout type
 */
declare enum TwitchEmbedLayout {
    /**
     * Default if channel is provided, and only supported for live content.
     * Shows both video and chat side-by-side. At narrow sizes, chat renders under the video player
     */
    VIDEO_WITH_CHAT = "video-with-chat",
    /**
     * Default if channel is not provided. Shows only the video player (omits chat)
     */
    VIDEO = "video"
}
/**
 * Embed color theme
 */
declare enum TwitchEmbedTheme {
    /**
     * Light Twitch embed color theme
     */
    LIGHT = "light",
    /**
     * Dark Twitch embed color theme
     */
    DARK = "dark"
}
/**
 * Provides a list of subscribable Twitch player embed events
 */
declare enum TwitchEmbedEvents {
    /**
     * Player just unpaused, will either start video playback or start buffering
     */
    PLAY = "play",
    /**
     * Player is ready to accept function calls
     */
    READY = "ready"
}

/**
 * Embed playback stats
 */
interface TwitchPlaybackStats {
    /**
     * The version of the Twitch video player backend
     */
    readonly backendVersion: string;
    /**
     * The size of the video buffer in seconds
     */
    readonly bufferSize: number;
    /**
     * Codecs currently in use, comma-separated (video,audio)
     */
    readonly codecs: string;
    /**
     * The current size of the video player element (eg. 850x480)
     */
    readonly displayResolution: string;
    /**
     * The video playback rate in frames per second. Not available on all browsers
     */
    readonly fps: number;
    /**
     * Current latency to the broadcaster in seconds. Only available for live content
     */
    readonly hlsLatencyBroadcaster: number;
    /**
     * The playback bitrate in Kbps
     */
    readonly playbackRate: number;
    /**
     * The number of dropped frames
     */
    readonly skippedFrames: number;
    /**
     * The native resolution of the current video (eg. 640x480)
     */
    readonly videoResolution: string;
}

/**
 * Twitch player options
 */
interface TwitchPlayerOptions {
    /**
     * Height of the embedded window, in pixels. Can be expressed as a percentage, by passing a string like `100%`. Recommended minimum: `300`
     */
    readonly height: number | string;
    /**
     * Width of the embedded window, in pixels. Can be expressed as a percentage, by passing a string like `50%`. Recommended minimum: `400`
     */
    readonly width: number | string;
    /**
     * Only required if your site is embedded on any domain(s) other than the one that instantiates the Twitch embed.
     *
     * Example parent parameter: `["streamernews.example.com", "embed.example.com"]`
     */
    readonly parent?: string[];
    /**
     * Channel name (for a live stream).
     *
     * If channel is specified along with video and/or collection, only channel is used.
     *
     * To change the channel or video later, use `setChannel`, `setVideo`, or `setCollection`
     */
    readonly channel?: string;
    /**
     * Video ID.
     *
     * If both video and collection are specified, the specified collection starts playing from the specified video.
     * If the video is not in the collection, collection is ignored and the specified video is played.
     *
     * To change the channel or video later, use `setChannel`, `setVideo`, or `setCollection`
     */
    readonly video?: string;
    /**
     * Collection ID.
     *
     * If both video and collection are specified, the specified collection starts playing from the specified video.
     * If the video is not in the collection, collection is ignored and the specified video is played.
     *
     * To change the channel or video later, use `setChannel`, `setVideo`, or `setCollection`
     */
    readonly collection?: string;
    /**
     * If `true`, the video starts playing automatically, without the user clicking play.
     * The exception is mobile devices, on which video cannot be played without user interaction. Default: `true`
     */
    readonly autoplay?: boolean;
    /**
     * Specifies whether the initial state of the video is muted. Default: `false`
     */
    readonly muted?: boolean;
    /**
     * Only valid for Video on Demand content. Time in the video where playback starts.
     * Specifies hours, minutes, and seconds. Default: 0h0m0s (the start of the video)
     */
    readonly time?: string;
}
/**
 * Twitch player events
 */
declare enum TwitchPlayerEvents {
    /**
     * Closed captions are found in the video content being played. This event will be emitted once for each new batch of captions,
     * in sync with the corresponding video content. The event payload is a string containing the caption content
     */
    CAPTIONS = "captions",
    /**
     * Video or stream ends
     */
    ENDED = "ended",
    /**
     * Player is paused. Buffering and seeking is not considered paused
     */
    PAUSE = "pause",
    /**
     * Player just unpaused, will either start video playback or start buffering
     */
    PLAY = "play",
    /**
     * Player playback was blocked. Usually fired after an unmuted autoplay or unmuted programmatic call on `play()`
     */
    PLAYBACK_BLOCKED = "playbackBlocked",
    /**
     * Player started video playback
     */
    PLAYING = "playing",
    /**
     * Loaded channel goes offline
     */
    OFFLINE = "offline",
    /**
     * Loaded channel goes online
     */
    ONLINE = "online",
    /**
     * Player is ready to accept function calls
     */
    READY = "ready",
    /**
     * User has used the player controls to seek a VOD, the `seek()` method has been called, or live playback has seeked to sync up after being paused
     */
    SEEK = "seek"
}

/**
 * Embed player video quality
 */
interface Quality {
    bitrate: number;
    codecs: string;
    framerate: number;
    group: string;
    height: number;
    isDefault: boolean;
    name: string;
    width: number;
}

/**
 * Twitch player
 */
declare class TwitchPlayer {
    private player;
    /**
     * Creates a new Twitch player from player instance
     * @param player player instance
     */
    constructor(player: TwitchPlayer);
    /**
     * Creates a new Twitch player given a <div> element and some options for the player
     * @param divId the div HTML element where the player will appear
     * @param options the player initialization options
     * @constructor creates a new Twitch player instance
     */
    static CreatePlayer(divId: string, options: TwitchPlayerOptions): TwitchPlayer;
    /**
     * Add event listener to twitch player
     * @param event player event
     * @param callback function
     */
    addEventListener(event: TwitchPlayerEvents, callback: Function): void;
    /**
     * Remove event listener from twitch player
     * @param event player event
     * @param callback function
     */
    removeEventListener(event: TwitchPlayerEvents, callback: Function): void;
    /**
     * Disables display of Closed Captions
     */
    disableCaptions(): void;
    /**
     * Enables display of Closed Captions
     */
    enableCaptions(): void;
    /**
     * Pauses the player
     */
    pause(): void;
    /**
     * Begins playing the specified video
     */
    play(): void;
    /**
     * Seeks to the specified `timestamp` (in seconds) in the video
     * @param timestamp time
     */
    seek(timestamp: number): void;
    /**
     * Sets the channel to be played
     * @param channel channel name
     */
    setChannel(channel: string): void;
    /**
     * Sets the collection to be played.
  
      Optionally also specifies the video within the collection, from which to start playback.
      If a `videoId` is not provided here or the specified video is not part of the collection,
      playback starts with the first video in the collection
     * @param collectionId collection id
     * @param videoId video id
     */
    setCollection(collectionId: string, videoId?: string): void;
    /**
     * Sets the quality of the video.
  
      `quality` should be a string value returned by `getQualities()`
     * @param quality
     */
    setQuality(quality: string): void;
    /**
     * Sets the video to be played to be played and starts playback at `timestamp` (in seconds)
     * @param videoId
     * @param timestamp
     */
    setVideo(videoId: string, timestamp: number): void;
    /**
     * Returns true if the player is muted; otherwise, false
     * @returns mute state
     */
    getMuted(): boolean;
    /**
     * If true, mutes the player; otherwise, unmutes it. This is independent of the volume setting
     * @param muted mute state
     */
    setMuted(muted: boolean): void;
    /**
     * Returns the volume level
     * @returns value between 0.0 and 1.0
     */
    getVolume(): number;
    /**
     * Sets the volume to the specified volume level
     * @param volumeLevel value between 0.0 and 1.0
     */
    setVolume(volumeLevel: number): void;
    /**
     * Returns an object with statistics on the playerded video player and the current live stream or VOD
     * @returns object with statistics
     */
    getPlaybackStats(): TwitchPlaybackStats;
    /**
     * Returns the channel’s name. Works only for live streams, not VODs
     * @returns channel name
     */
    getChannel(): string;
    /**
     * Returns the current video’s timestamp, in seconds. Works only for VODs, not live streams
     * @returns video timestamp
     */
    getCurrentTime(): number;
    /**
     * Returns the duration of the video, in seconds. Works only for VODs,not live streams
     * @returns duration of the video
     */
    getDuration(): number;
    /**
     * Returns true if the live stream or VOD has ended; otherwise, false
     * @returns stream status
     */
    getEnded(): boolean;
    /**
     * Returns the available video qualities
     * @returns video qualities
     */
    getQualities(): Quality[];
    /**
     * Returns the current quality of video playback
     * @returns state of playback
     */
    getQuality(): string;
    /**
     * Returns the video ID. Works only for VODs, not live streams
     * @returns video id
     */
    getVideo(): string;
    /**
     * Returns true if the video is paused; otherwise, false. Buffering or seeking is considered playing.
     * @returns pause state
     */
    isPaused(): boolean;
}

/**
 * Twitch embed player with/out chat
 */
declare class TwitchEmbed {
    private readonly embed;
    private readonly player;
    private readonly embedOptions;
    private readonly divId;
    /**
     * Creates a new Twitch embed instance
     * @param divId the div HTML element where the player will appear
     * @param options the player initialization options
     */
    constructor(divId: string, options: TwitchEmbedOptions);
    /**
     * Add event listener to twitch embed
     * @param event embed event
     * @param callback function
     */
    addEventListener(event: TwitchEmbedEvents, callback: Function): void;
    /**
     * Remove event listener from twitch embed
     * @param event embed event
     * @param callback function
     */
    removeEventListener(event: TwitchEmbedEvents, callback: Function): void;
    /**
     * Get div id for ijecting
     * @returns div id
     */
    getDivId(): string;
    /**
     * Get twitch embed player
     * @returns twitch player object
     */
    getPlayer(): TwitchPlayer;
    /**
     * Disables display of Closed Captions
     */
    disableCaptions(): void;
    /**
     * Enables display of Closed Captions
     */
    enableCaptions(): void;
    /**
     * Pauses the player
     */
    pause(): void;
    /**
     * Begins playing the specified video
     */
    play(): void;
    /**
     * Seeks to the specified `timestamp` (in seconds) in the video
     * @param timestamp time
     */
    seek(timestamp: number): void;
    /**
     * Sets the channel to be played
     * @param channel channel name
     */
    setChannel(channel: string): void;
    /**
     * Sets the collection to be played.
  
      Optionally also specifies the video within the collection, from which to start playback.
      If a `videoId` is not provided here or the specified video is not part of the collection,
      playback starts with the first video in the collection
     * @param collectionId collection id
     * @param videoId video id
     */
    setCollection(collectionId: string, videoId?: string): void;
    /**
     * Sets the quality of the video.
  
      `quality` should be a string value returned by `getQualities()`
     * @param quality
     */
    setQuality(quality: string): void;
    /**
     * Sets the video to be played to be played and starts playback at `timestamp` (in seconds)
     * @param videoId
     * @param timestamp
     */
    setVideo(videoId: string, timestamp: number): void;
    /**
     * Returns true if the player is muted; otherwise, false
     * @returns mute state
     */
    getMuted(): boolean;
    /**
     * If true, mutes the player; otherwise, unmutes it. This is independent of the volume setting
     * @param muted mute state
     */
    setMuted(muted: boolean): void;
    /**
     * Returns the volume level
     * @returns value between 0.0 and 1.0
     */
    getVolume(): number;
    /**
     * Sets the volume to the specified volume level
     * @param volumeLevel value between 0.0 and 1.0
     */
    setVolume(volumeLevel: number): void;
    /**
     * Returns an object with statistics on the embedded video player and the current live stream or VOD
     * @returns object with statistics
     */
    getPlaybackStats(): TwitchPlaybackStats;
    /**
     * Returns the channel’s name. Works only for live streams, not VODs
     * @returns channel name
     */
    getChannel(): string;
    /**
     * Returns the current video’s timestamp, in seconds. Works only for VODs, not live streams
     * @returns video timestamp
     */
    getCurrentTime(): number;
    /**
     * Returns the duration of the video, in seconds. Works only for VODs,not live streams
     * @returns duration of the video
     */
    getDuration(): number;
    /**
     * Returns true if the live stream or VOD has ended; otherwise, false
     * @returns stream status
     */
    getEnded(): boolean;
    /**
     * Returns the available video qualities
     * @returns video qualities
     */
    getQualities(): Quality[];
    /**
     * Returns the current quality of video playback
     * @returns state of playback
     */
    getQuality(): string;
    /**
     * Returns the video ID. Works only for VODs, not live streams
     * @returns video id
     */
    getVideo(): string;
    /**
     * Returns true if the video is paused; otherwise, false. Buffering or seeking is considered playing.
     * @returns pause state
     */
    isPaused(): boolean;
}

export { type Quality, TwitchEmbed, TwitchEmbedEvents, TwitchEmbedLayout, type TwitchEmbedOptions, TwitchEmbedTheme, type TwitchPlaybackStats, TwitchPlayer, TwitchPlayerEvents, type TwitchPlayerOptions };