Skip to content

A modern and easy to use dashboard. 80+ integrations. 20K+ icons built in. Authentication out of the box. No YAML, drag and drop configuration.

24.2 KB
Raw Blame
import { parseStringPromise } from "xml2js";
import { z } from "zod/v4";

import { ParseError, ResponseError } from "@homarr/common/server";
import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";
import type { UndiciHttpAgent } from "@homarr/core/infrastructure/http";
import { createCertificateAgentAsync, fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
import { createLogger } from "@homarr/core/infrastructure/logs";
import { ImageProxy } from "@homarr/image-proxy";

import type { IntegrationTestingInput } from "../base/integration";
import { Integration } from "../base/integration";
import { TestConnectionError } from "../base/test-connection/test-connection-error";
import type { TestingResult } from "../base/test-connection/test-connection-service";
import type { IMediaServerIntegration } from "../interfaces/media-server/media-server-integration";
import type { CurrentSessionsInput, StreamSession } from "../interfaces/media-server/media-server-types";
import type { IMediaReleasesIntegration, MediaRelease } from "../types";
import type { PlexResponse } from "./interface";

const logger = createLogger({ module: "plexIntegration" });

function parseOptionalNumber(value: string | undefined): number | null {
  if (!value) {
    return null;
  }

  const parsed = Number(value);
  return Number.isNaN(parsed) ? null : parsed;
}

function parseLocation(value: string | undefined): "lan" | "wan" | null {
  return value === "lan" || value === "wan" ? value : null;
}

function parsePlaybackState(value: string | undefined): "playing" | "paused" | "buffering" | null {
  return value === "playing" || value === "paused" || value === "buffering" ? value : null;
}

function parseResolution(
  width: string | undefined,
  height: string | undefined,
): { width: number; height: number } | null {
  const parsedWidth = parseOptionalNumber(width);
  const parsedHeight = parseOptionalNumber(height);
  return parsedWidth !== null && parsedHeight !== null ? { width: parsedWidth, height: parsedHeight } : null;
}

// Seasons in /library/recentlyAdded use "/library/metadata/{ratingKey}/children" as key, episodes reference their
// season through parentKey "/library/metadata/{ratingKey}". /library/recentlyAdded can return either of them for the
// same content, so both are mapped to the season they belong to.
function seasonKeyOf(item: RecentlyAddedItem): string | null {
  if (item.type === "season") return item.key.replace(/\/children$/, "");
  if (item.type === "episode") return item.parentKey ?? null;
  return null;
}

function formatEpisodeSubtitle(episode: RecentlyAddedEpisode): string | undefined {
  if (episode.parentIndex === undefined || episode.index === undefined) return undefined;

  const seasonEpisode = `S${String(episode.parentIndex).padStart(2, "0")}E${String(episode.index).padStart(2, "0")}`;
  return episode.title ? `${seasonEpisode} \u2013 ${episode.title}` : seasonEpisode;
}

function episodeImages(episode: RecentlyAddedEpisode): RecentlyAddedItem["Image"] {
  const images: NonNullable<RecentlyAddedItem["Image"]> = [];
  const poster = episode.grandparentThumb ?? episode.parentThumb ?? episode.thumb;
  const backdrop = episode.art ?? episode.grandparentArt;
  if (poster) images.push({ type: "coverPoster", url: poster });
  if (backdrop) images.push({ type: "background", url: backdrop });
  return images.length > 0 ? images : undefined;
}

function parseReleaseDate(item: RecentlyAddedItem): Date {
  const airDate = item.originallyAvailableAt;
  if (!airDate) return new Date(item.addedAt * 1000);
  return new Date(airDate);
}

/**
 * `/library/recentlyAdded` lists seasons with the `addedAt` of the season itself, so episodes added to an existing
 * season never surface. Merges the most recently added episode of every season into the list: entries that received
 * newer episodes are bumped to the episode's `addedAt`, seasons that are no longer part of `/library/recentlyAdded`
 * are re-created from the episode metadata. Entries whose show or season is already listed are never duplicated.
 */
function mergeRecentlyAddedEpisodes(items: RecentlyAddedItem[], episodes: RecentlyAddedEpisode[]): MergedItem[] {
  if (episodes.length === 0) return items;

  // Episodes are sorted by addedAt descending, so the first one per season or show is the newest
  const newestEpisodeBySeasonKey = new Map<string, RecentlyAddedEpisode>();
  const newestEpisodeByShowKey = new Map<string, RecentlyAddedEpisode>();
  for (const episode of episodes) {
    if (episode.parentKey && !newestEpisodeBySeasonKey.has(episode.parentKey)) {
      newestEpisodeBySeasonKey.set(episode.parentKey, episode);
    }
    if (episode.grandparentKey && !newestEpisodeByShowKey.has(episode.grandparentKey)) {
      newestEpisodeByShowKey.set(episode.grandparentKey, episode);
    }
  }

  const bumpedItems = items.map((item): MergedItem => {
    const seasonKey = seasonKeyOf(item);
    let episode: RecentlyAddedEpisode | undefined;
    if (item.type === "show") episode = newestEpisodeByShowKey.get(item.key);
    else if (seasonKey) episode = newestEpisodeBySeasonKey.get(seasonKey);
    if (!episode || (item.type !== "show" && episode.addedAt <= item.addedAt)) return item;

    if (item.type === "episode") {
      return {
        ...item,
        key: episode.key,
        Media: undefined,
        title: episode.title ?? item.title,
        parentTitle: episode.parentTitle ?? item.parentTitle,
        grandparentTitle: episode.grandparentTitle ?? item.grandparentTitle,
        Image: episodeImages(episode) ?? item.Image,
        summary: episode.summary,
        duration: episode.duration,
        addedAt: episode.addedAt,
        originallyAvailableAt: episode.originallyAvailableAt,
        latestEpisode: episode,
      };
    }

    return {
      ...item,
      addedAt: Math.max(item.addedAt, episode.addedAt),
      originallyAvailableAt: episode.originallyAvailableAt ?? item.originallyAvailableAt,
      latestEpisode: episode,
    };
  });

  const listedKeys = new Set(
    items.flatMap((item) => (item.type === "show" ? [item.key] : [seasonKeyOf(item)])).filter((key) => key !== null),
  );
  const missingSeasons = [...newestEpisodeBySeasonKey.entries()]
    .filter(([seasonKey, episode]) => !listedKeys.has(seasonKey) && !listedKeys.has(episode.grandparentKey ?? ""))
    .map(([seasonKey, episode]): MergedItem => {
      return {
        key: `${seasonKey}/children`,
        type: "season",
        title: episode.parentTitle ?? (episode.parentIndex !== undefined ? `Season ${episode.parentIndex}` : "Season"),
        parentTitle: episode.grandparentTitle,
        addedAt: episode.addedAt,
        originallyAvailableAt: episode.originallyAvailableAt,
        latestEpisode: episode,
        Image: episodeImages(episode),
      };
    });

  return [...bumpedItems, ...missingSeasons].toSorted((itemA, itemB) => itemB.addedAt - itemA.addedAt);
}

function isStreamDirect(decision: string | undefined): boolean {
  // Plex reports "transcode" when a stream is re-encoded. "copy" (remuxed
  // without re-encoding) and an absent decision both count as direct.
  return decision !== "transcode";
}

export class PlexIntegration extends Integration implements IMediaServerIntegration, IMediaReleasesIntegration {
  public async getCurrentSessionsAsync(_options: CurrentSessionsInput): Promise<StreamSession[]> {
    const token = super.getSecretValue("apiKey");

    const response = await fetchWithTrustedCertificatesAsync(this.url("/status/sessions"), {
      headers: {
        "X-Plex-Token": token,
      },
    });
    const body = await response.text();
    // convert xml response to objects, as there is no JSON api
    const data = await PlexIntegration.parseXmlAsync<PlexResponse>(body);
    const mediaContainer = data.MediaContainer;
    const mediaElements = [mediaContainer.Video ?? [], mediaContainer.Track ?? []].flat();

    // no sessions are open or available
    if (mediaElements.length === 0) {
      logger.info("No active video sessions found in MediaContainer");
      return [];
    }

    const medias = mediaElements
      .map((mediaElement): StreamSession | undefined => {
        const userElement = mediaElement.User ? mediaElement.User[0] : undefined;
        const playerElement = mediaElement.Player ? mediaElement.Player[0] : undefined;
        const sessionElement = mediaElement.Session ? mediaElement.Session[0] : undefined;
        const transcodeElement = mediaElement.TranscodeSession ? mediaElement.TranscodeSession[0] : undefined;
        const mediaInfoElement = mediaElement.Media ? mediaElement.Media[0] : undefined;

        if (!playerElement) {
          return undefined;
        }

        const positionMs = parseOptionalNumber(mediaElement.$.viewOffset);
        const durationMs = parseOptionalNumber(mediaElement.$.duration);

        const playbackState = parsePlaybackState(playerElement.$.state);

        const location = parseLocation(sessionElement?.$.location);

        const streams = mediaInfoElement?.Part?.[0]?.Stream ?? [];
        const videoStream = streams.find((stream) => stream.$.streamType === "1");
        const audioStream = streams.find((stream) => stream.$.streamType === "2");

        const isVideoDirect = isStreamDirect(transcodeElement?.$.videoDecision);
        const isAudioDirect = isStreamDirect(transcodeElement?.$.audioDecision);
        const containerChanged = Boolean(
          transcodeElement?.$.container &&
          mediaInfoElement?.$.container &&
          transcodeElement.$.container !== mediaInfoElement.$.container,
        );
        const bitrateKbps =
          parseOptionalNumber(sessionElement?.$.bandwidth) ?? parseOptionalNumber(mediaInfoElement?.$.bitrate);

        return {
          sessionId: sessionElement?.$.id ?? "unknown",
          sessionName: `${playerElement.$.product} (${playerElement.$.title})`,
          user: {
            userId: userElement?.$.id ?? "Anonymous",
            username: userElement?.$.title ?? "Anonymous",
            profilePictureUrl: userElement?.$.thumb ?? null,
          },
          currentlyPlaying: {
            type: mediaElement.$.live === "1" ? "tv" : PlexIntegration.getCurrentlyPlayingType(mediaElement.$.type),
            name: mediaElement.$.grandparentTitle ?? mediaElement.$.title ?? "Unknown",
            seasonName: mediaElement.$.parentTitle,
            seasonNumber: mediaElement.$.type === "episode" ? parseOptionalNumber(mediaElement.$.parentIndex) : null,
            episodeName: mediaElement.$.type === "episode" ? (mediaElement.$.title ?? null) : null,
            episodeNumber: mediaElement.$.type === "episode" ? parseOptionalNumber(mediaElement.$.index) : null,
            albumName: mediaElement.$.type === "track" ? (mediaElement.$.parentTitle ?? null) : null,
            episodeCount: parseOptionalNumber(mediaElement.$.index),
            playback: {
              state: playbackState,
              positionMs,
              durationMs,
            },
            location,
            metadata: {
              video: {
                resolution: parseResolution(videoStream?.$.width, videoStream?.$.height),
                frameRate: parseOptionalNumber(videoStream?.$.frameRate),
              },
              audio: {
                channelCount: parseOptionalNumber(audioStream?.$.channels),
                codec: audioStream?.$.codec ?? mediaInfoElement?.$.audioCodec ?? null,
              },
              transcoding: {
                container: transcodeElement?.$.container ?? null,
                resolution: parseResolution(transcodeElement?.$.width, transcodeElement?.$.height),
                target: {
                  audioCodec: transcodeElement?.$.audioCodec ?? null,
                  videoCodec: transcodeElement?.$.videoCodec ?? null,
                },
                isVideoDirect,
                isAudioDirect,
                containerChanged,
              },
              bitrateKbps,
            },
          },
        };
      })
      .filter((session): session is StreamSession => session !== undefined);

    return medias;
  }

  public async getMediaReleasesAsync(): Promise<MediaRelease[]> {
    const token = super.getSecretValue("apiKey");
    // A single dispatcher for all requests of this call, so the trusted certificates are read once and the
    // connection to Plex is reused instead of opening a new TLS connection per library.
    const dispatcher = await createCertificateAgentAsync(undefined, { bodyTimeout: REQUEST_TIMEOUT_MS });

    try {
      return await this.getMediaReleasesWithDispatcherAsync(token, dispatcher);
    } finally {
      await dispatcher.close();
    }
  }

  private async getMediaReleasesWithDispatcherAsync(token: string, dispatcher: UndiciHttpAgent) {
    // The episode requests are an addition to /library/recentlyAdded and run alongside it instead of after it
    const [machineIdentifier, data, episodes] = await Promise.all([
      this.getMachineIdentifierAsync(dispatcher),
      this.fetchJsonAsync("/library/recentlyAdded", dispatcher).then(
        async (json) => await recentlyAddedSchema.parseAsync(json),
      ),
      this.getRecentlyAddedEpisodesAsync(dispatcher),
    ]);
    const recentlyAddedItems = mergeRecentlyAddedEpisodes(data.MediaContainer.Metadata ?? [], episodes)
      .filter((item) => item.Image)
      .slice(0, MEDIA_RELEASES_LIMIT);
    const imageProxy = new ImageProxy();

    const images =
      recentlyAddedItems
        .filter((item) => item.Image)
        .flatMap((item) => [
          {
            mediaKey: item.key,
            type: "poster",
            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
            url: item.Image!.find((image) => image?.type === "coverPoster")?.url,
          },
          {
            mediaKey: item.key,
            type: "backdrop",
            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
            url: item.Image!.find((image) => image?.type === "background")?.url,
          },
        ])
        .filter(
          (image): image is { mediaKey: string; type: "poster" | "backdrop"; url: string } => image.url !== undefined,
        ) ?? [];

    const proxiedImages = await Promise.all(
      images.map(async (image) => {
        const imageUrl = super.url(image.url as `/${string}`);
        const proxiedImageUrl = await imageProxy
          .createImageAsync(imageUrl.toString(), {
            "X-Plex-Token": token,
          })
          .catch((error) => {
            logger.debug(new Error("Failed to proxy image", { cause: error }));
            return undefined;
          });
        return {
          mediaKey: image.mediaKey,
          type: image.type,
          url: proxiedImageUrl,
        };
      }),
    );

    const imageUrlsByType = {
      poster: new Map<string, string | undefined>(),
      backdrop: new Map<string, string | undefined>(),
    };
    for (const image of proxiedImages) {
      const urls = imageUrlsByType[image.type];
      // Match find's first-entry semantics, including a failed proxy result.
      if (!urls.has(image.mediaKey)) urls.set(image.mediaKey, image.url);
    }

    const media = recentlyAddedItems
      .filter((item) => item.Image)
      .map((item) => {
        let latestEpisodeSubtitle: string | undefined;
        if (item.latestEpisode) {
          latestEpisodeSubtitle = formatEpisodeSubtitle(item.latestEpisode);
          if (!latestEpisodeSubtitle && item.type === "show") latestEpisodeSubtitle = item.latestEpisode.title;
        }
        const title =
          item.type === "episode"
            ? (item.grandparentTitle ?? item.title)
            : item.type === "season"
              ? (item.parentTitle ?? item.title)
              : item.title;

        return {
          id: item.Media?.at(0)?.id.toString() ?? item.key,
          type: mapType(item.type),
          title,
          subtitle: latestEpisodeSubtitle ?? (title === item.title ? item.tagline : item.title),
          description: item.summary,
          releaseDate: parseReleaseDate(item),
          releaseDateIsDateOnly: /^\d{4}-\d{2}-\d{2}$/.test(item.originallyAvailableAt ?? ""),
          imageUrls: {
            poster: imageUrlsByType.poster.get(item.key),
            backdrop: imageUrlsByType.backdrop.get(item.key),
          },
          producer: item.studio,
          rating: item.rating?.toFixed(1),
          tags: item.Genre?.map((genre) => genre.tag) ?? [],
          href: super
            .url(
              // Url with children on the end results in infinite loading screen, see https://github.com/homarr-labs/homarr/issues/4078
              `/web/index.html#!/server/${machineIdentifier}/details?key=${encodeURIComponent(item.key.replace("/children", ""))}`,
            )
            .toString(),
          length: item.duration ? Math.round(item.duration / 1000) : undefined,
        };
      });

    return media;
  }

  /**
   * Most recently added episodes of every show library, newest first. Never rejects: a library that fails or times
   * out is skipped so the remaining libraries still contribute, and an empty result keeps the seasons only list.
   */
  private async getRecentlyAddedEpisodesAsync(dispatcher: UndiciHttpAgent): Promise<RecentlyAddedEpisode[]> {
    const showSections = await this.getShowSectionsAsync(dispatcher);

    const episodesPerSection = await Promise.allSettled(
      showSections.map(async (section) => {
        const data = await recentlyAddedEpisodesSchema.parseAsync(
          await this.fetchJsonAsync(
            `/library/sections/${encodeURIComponent(section.key)}/all?type=4&sort=addedAt:desc&X-Plex-Container-Start=0&X-Plex-Container-Size=${EPISODES_PAGE_SIZE}`,
            dispatcher,
          ),
        );
        return data.MediaContainer.Metadata ?? [];
      }),
    );

    return episodesPerSection
      .flatMap((result, index) => {
        if (result.status === "fulfilled") return result.value;

        logger.warn(
          new ErrorWithMetadata(
            "Failed to fetch recently added episodes of Plex library",
            { section: showSections[index]?.key ?? "unknown" },
            { cause: result.reason },
          ),
        );
        return [];
      })
      .toSorted((episodeA, episodeB) => episodeB.addedAt - episodeA.addedAt);
  }

  private async getShowSectionsAsync(dispatcher: UndiciHttpAgent) {
    try {
      const sections = await librarySectionsSchema.parseAsync(
        await this.fetchJsonAsync("/library/sections", dispatcher),
      );
      return sections.MediaContainer.Directory?.filter((section) => section.type === "show") ?? [];
    } catch (error) {
      logger.warn(
        new Error("Failed to list Plex libraries, media releases fall back to seasons only", { cause: error }),
      );
      return [];
    }
  }

  /**
   * Wraps fetchWithTrustedCertificatesAsync with the Plex token and JSON accept header used by all JSON endpoints.
   * The dispatcher carries the body timeout, `timeout` covers the response headers.
   */
  private async fetchJsonAsync(path: `/${string}`, dispatcher: UndiciHttpAgent): Promise<unknown> {
    const token = super.getSecretValue("apiKey");
    const response = await fetchWithTrustedCertificatesAsync(super.url(path), {
      dispatcher,
      timeout: REQUEST_TIMEOUT_MS,
      headers: {
        "X-Plex-Token": token,
        Accept: "application/json",
      },
    });

    if (!response.ok) {
      throw new ResponseError(response);
    }

    return await response.json();
  }

  private async getMachineIdentifierAsync(dispatcher: UndiciHttpAgent): Promise<string> {
    const data = await identitySchema.parseAsync(await this.fetchJsonAsync("/identity", dispatcher));
    return data.MediaContainer.machineIdentifier;
  }

  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
    const token = super.getSecretValue("apiKey");

    const response = await input.fetchAsync(super.url("/prefs"), {
      headers: {
        "X-Plex-Token": token,
        Accept: "application/json",
      },
    });

    if (!response.ok) return TestConnectionError.StatusResult(response);

    return { success: true };
  }

  static async parseXmlAsync<T>(xml: string): Promise<T> {
    try {
      return (await parseStringPromise(xml)) as Promise<T>;
    } catch (error) {
      throw new ParseError(
        "Invalid xml format",
        error instanceof Error
          ? {
              cause: error,
            }
          : undefined,
      );
    }
  }

  static getCurrentlyPlayingType(type: string): NonNullable<StreamSession["currentlyPlaying"]>["type"] {
    switch (type) {
      case "movie":
        return "movie";
      case "episode":
        return "video";
      case "track":
        return "audio";
      default:
        return "video";
    }
  }
}

// Same limit as the Jellyfin and Emby integrations
const MEDIA_RELEASES_LIMIT = 100;
// Default page size of /library/recentlyAdded, enough to cover the newest episode of every recently updated season
const EPISODES_PAGE_SIZE = 50;
// A stalled Plex request must not block the merge, the fallback or the widget
const REQUEST_TIMEOUT_MS = 10_000;

const recentlyAddedItemSchema = z.object({
  key: z.string(),
  parentKey: z.string().optional(), // season of an episode, for example "/library/metadata/123"
  studio: z.string().optional(),
  type: z.string(), // For example "movie", "album"
  title: z.string(),
  parentTitle: z.string().optional(),
  grandparentTitle: z.string().optional(),
  summary: z.string().optional(),
  duration: z.number().optional(),
  addedAt: z.number(),
  rating: z.number().optional(),
  tagline: z.string().optional(),
  originallyAvailableAt: z.string().optional(),
  Media: z
    .array(
      z.object({
        id: z.number(),
      }),
    )
    .optional(),
  Image: z
    .array(
      z
        .object({
          type: z.string(), // for example "coverPoster" or "background"
          url: z.string(),
        })
        .optional(),
    )
    .optional(),
  Genre: z
    .array(
      z.object({
        tag: z.string(),
      }),
    )
    .optional(),
});

type RecentlyAddedItem = z.infer<typeof recentlyAddedItemSchema>;

/**
 * A recently added item together with the newest episode that put it at its position, if any.
 */
interface MergedItem extends RecentlyAddedItem {
  latestEpisode?: RecentlyAddedEpisode;
}

// https://plexapi.dev/api-reference/library/get-recently-added
const recentlyAddedSchema = z.object({
  MediaContainer: z.object({
    Metadata: z.array(recentlyAddedItemSchema).optional(),
  }),
});

// https://plexapi.dev/api-reference/library/get-all-libraries
const librarySectionsSchema = z.object({
  MediaContainer: z.object({
    Directory: z
      .array(
        z.object({
          key: z.string(),
          type: z.string(), // For example "movie", "show", "artist"
        }),
      )
      .optional(),
  }),
});

// https://plexapi.dev/api-reference/library/get-library-items with type=4 (episodes)
const recentlyAddedEpisodeSchema = z.object({
  key: z.string(),
  title: z.string().optional(), // episode title
  summary: z.string().optional(),
  duration: z.number().optional(),
  index: z.number().optional(), // episode number
  parentKey: z.string().optional(), // season, for example "/library/metadata/123"
  parentIndex: z.number().optional(), // season number
  parentTitle: z.string().optional(), // season title, for example "Season 2"
  parentThumb: z.string().optional(),
  thumb: z.string().optional(),
  grandparentKey: z.string().optional(), // show, for example "/library/metadata/122"
  grandparentTitle: z.string().optional(), // show title
  grandparentThumb: z.string().optional(),
  grandparentArt: z.string().optional(),
  art: z.string().optional(),
  addedAt: z.number(),
  originallyAvailableAt: z.string().optional(),
});

type RecentlyAddedEpisode = z.infer<typeof recentlyAddedEpisodeSchema>;

const recentlyAddedEpisodesSchema = z.object({
  MediaContainer: z.object({
    Metadata: z.array(recentlyAddedEpisodeSchema).optional(),
  }),
});

// https://plexapi.dev/api-reference/server/get-server-identity
const identitySchema = z.object({
  MediaContainer: z.object({
    machineIdentifier: z.string(),
  }),
});

const mapType = (type: string): "movie" | "tv" | "music" | "unknown" => {
  switch (type) {
    case "movie":
      return "movie";
    case "show":
    case "season":
    case "episode":
      return "tv";
    case "album":
    case "artist":
    case "track":
      return "music";
    default:
      return "unknown";
  }
};