@ctrl/plex

@ctrl/plex

npm coverage

A TypeScript Plex API client based on pkkid/python-plexapi

npm install @ctrl/plex

https://ctrl-plex.vercel.app

Create a plex connection

import { MyPlexAccount } from '@ctrl/plex';

const account = await new MyPlexAccount('http://localhost:32400', 'username', 'password').connect();
const resource = await account.resource('<SERVERNAME>');
const plex = await resource.connect();
const library = await plex.library();
import { MovieSection } from '@ctrl/plex';

// Pass MovieSection generic because the section title doesn't imply a section type.
const section = await library.section<MovieSection>('Movies');
// Get an array of Movie objects
const results = await section.search({ unwatched: true });
const library = await plex.library();
const section = await library.section<MovieSection>('Movies');
const results = await section.search({ title: 'Rush Hour' });
const results = await plex.search('Arnold');
// Each hub represents a single Hub (or category) in the PlexServer search (movie, actor, etc)
for (const hub of results) {
// Log first result in each category
console.log(hub?.Metadata?.[0]);
}
import { ShowSection } from '@ctrl/plex';

// Pass ShowSection generic because the section title doesn't imply a section type.
const section = await library.section<ShowSection>('TV Shows');
// Get an array of Show objects
const results = await section.search({ title: 'Silicon Valley' });
const episodes = await results[0].episodes();

JS is a different language and some methods of the api were not possible. Chaining functions with requests must be awaited mostly individually. Constructors in JS don't typically make requests and accessing properties normally cannot make requests either.

Tests are run against a real instance of plex.

Setup test environment variables, create a plex account just for testing. Using a real account will break everything

export PLEX_USERNAME=email
export PLEX_PASSWORD=password

Claim server and setup test content (once)

npm run claim-server && npm run add-media

Run tests

npm test

Post testing, remove plex server from account. Warning this is destructive. Do not use this on a real plex account.

npm run test-cleanup

get a claim token from https://www.plex.tv/claim/ export PLEX_CLAIM_TOKEN=claim-token

docker run -d \
--name=plex \
--net=host \
-h orbstack \
-p 32400:32400/tcp \
-p 32400:32400 \
-p 1900:1900/udp \
-p 5353:5353/udp \
-p 8324:8324 \
-p 32410:32410/udp \
-p 32412:32412/udp \
-p 32413:32413/udp \
-p 32414:32414/udp \
-p 32469:32469 \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=Etc/UTC \
-e VERSION=docker \
-e PLEX_CLAIM=$PLEX_CLAIM_TOKEN \
-v /Users/scooper/gh/plex/plex/media/db:/config \
-v /Users/scooper/gh/plex/plex/media/transcode:/transcode \
-v /Users/scooper/gh/plex/plex/media:/data \
--restart unless-stopped \
lscr.io/linuxserver/plex:latest

bootstrap media

NODE_OPTIONS="--loader ts-node/esm" node scripts/bootstraptest.ts --no-docker --server-name=orbstack`