Skip to main content

​
Overview

MediaClient is the abstract base class that defines the common interface for all media server implementations (Emby, Plex, FolderServer, Local). All client implementations must extend this class and implement its abstract methods.
In most cases, you should use ClientFactory to create client instances rather than instantiating clients directly. The factory handles authentication and returns the appropriate client type based on the server configuration.

​
Constructor

constructor(config: ServerConfig)
​
config
ServerConfig
required
Server configuration object containing connection details

​
Example

import { MediaClient } from './services/MediaClient';
import { ServerConfig } from './types';

const config: ServerConfig = {
  url: 'https://emby.example.com',
  username: 'user',
  token: 'abc123',
  userId: 'user-id',
  serverType: 'emby'
};

// Extended by specific implementations
const client = new EmbyClient(config);

​
Properties

​
config
ServerConfig
The server configuration passed to the constructor

​
Abstract Methods

All extending classes must implement these methods:

​
authenticate

Authenticates a user with the media server. 
abstract authenticate(username: string, password: string): Promise<ServerConfig>
​
username
string
required
Username for authentication
​
password
string
required
Password or API token for authentication
​
return
Promise<ServerConfig>
Returns updated server configuration with authentication token and user ID

​
getLibraries

Fetches all available media libraries from the server. 
abstract getLibraries(): Promise<EmbyLibrary[]>
​
return
Promise<EmbyLibrary[]>
Array of library objects containing Id, Name, and CollectionType

​
getVideos

Fetches videos from a library with pagination and filtering. 
abstract getVideos(
  parentId: string | undefined,
  libraryName: string,
  feedType: FeedType,
  skip: number,
  limit: number,
  orientationMode: OrientationMode
): Promise<VideoResponse>
​
parentId
string | undefined
Library ID to fetch from, or undefined for favorites feed
​
libraryName
string
required
Name of the library for playlist/favorites management
​
feedType
FeedType
required
Type of feed: ‘latest’, ‘random’, or ‘favorites’
​
skip
number
required
Number of items to skip for pagination
​
limit
number
required
Maximum number of items to return
​
orientationMode
OrientationMode
required
Filter by video orientation: ‘vertical’, ‘horizontal’, or ‘both’
​
return
Promise<VideoResponse>
Object containing items array, nextStartIndex, and totalCount

​
getVideoUrl

Generates the streaming URL for a video item. 
abstract getVideoUrl(item: EmbyItem): string
​
item
EmbyItem
required
Video item to generate URL for
​
return
string
Streaming URL for the video

​
getImageUrl

Generates the URL for a video thumbnail or backdrop image. 
abstract getImageUrl(
  itemId: string,
  tag?: string,
  type?: 'Primary' | 'Backdrop'
): string
​
itemId
string
required
ID of the media item
​
tag
string
Image tag/hash for cache busting
​
type
'Primary' | 'Backdrop'
default:"'Primary'"
Type of image to fetch
​
return
string
URL for the image

​
getFavorites

Fetches the set of favorited item IDs for a library. 
abstract getFavorites(libraryName: string): Promise<Set<string>>
​
libraryName
string
required
Name of the library
​
return
Promise<Set<string>>
Set of item IDs that are favorited

​
toggleFavorite

Toggles the favorite status of a video item. 
abstract toggleFavorite(
  itemId: string,
  isFavorite: boolean,
  libraryName: string
): Promise<void>
​
itemId
string
required
ID of the item to toggle
​
isFavorite
boolean
required
Current favorite status (true means currently favorited)
​
libraryName
string
required
Name of the library for playlist management

​
Usage with ClientFactory

import { ClientFactory } from './services/clientFactory';
import { ServerConfig } from './types';

// Authenticate and get config
const config = await ClientFactory.authenticate(
  'emby',
  'https://emby.example.com',
  'username',
  'password'
);

// Create client instance
const client = ClientFactory.create(config);

// Use client methods
const libraries = await client.getLibraries();
const videos = await client.getVideos(
  libraries[0].Id,
  libraries[0].Name,
  'latest',
  0,
  15,
  'vertical'
);

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us