@api.video/media-descriptor

Media Descriptor Module

This module provides a robust way to handle video media descriptions for both VOD (Video on Demand) and Live streams. It consists of two main components: a factory to create media descriptors and a descriptor class to access media information.

Installation

npm install media-descriptor
# or
yarn add media-descriptor

MediaDescriptorFactory

The factory provides two methods to create a MediaDescriptor instance:

fromManifestUrl(url: string, options?: Options): Promise<MediaDescriptor>

Creates a MediaDescriptor from a manifest URL (m3u8).

const descriptor = await MediaDescriptorFactory.fromManifestUrl(
  "https://vod.api.video/vod/vi123456789/hls/manifest.m3u8"
);

Supported URL patterns:

• VOD public: domain.com/vod/videoId/hls/manifest.m3u8
• VOD private: domain.com/vod/videoId/token/tokenValue/hls/manifest.m3u8
• Live public: domain.com/videoId.m3u8
• Live private: domain.com/private/token/videoId.m3u8

Optional parameters:

• options.collectorDomain: Override the default analytics collector domain

fromVideoDescription(videoDescription: VideoDescription): Promise<MediaDescriptor>

Creates a MediaDescriptor from a video description object.

const descriptor = await MediaDescriptorFactory.fromVideoDescription({
  mediaId: "vi123456789",
  type: "vod",
  deliveryDomain: "vod.api.video",
  privateToken: "optional-token",
});

MediaDescriptor

The MediaDescriptor class provides access to all video-related information:

Basic Properties

• title: Video title
• mediaId: Unique video identifier
• mediaType: Either 'vod' or 'live'
• manifestUrl: HLS manifest URL
• mp4Url: Progressive download URL (VOD only)
• posterUrl: Thumbnail URL (VOD only)

Domains Information

const domains = descriptor.domains;
// {
//   delivery: "vod.api.video",
//   collector: "collector.api.video"
// }

Chapters Support

// List available chapter languages
const chapters = descriptor.chaptersEntries;
// Get chapter URL for a specific language
const chapterUrl = descriptor.getChapterUrl("en");

Summaries Support

// List available summaries
const summaries = descriptor.summaryEntries;
// [{ lang: 'en', generated: false }, { lang: 'fr', generated: true }]

// Get summary content
const summary = await descriptor.getSummary({ lang: "en", generated: false });
// {
//   title: string;
//   abstract: string;
//   takeaways: string[];
// }

Error Handling

The factory methods may throw:

• InvalidUrlError: When the manifest URL format is invalid
• VideoNotFoundError: When the video doesn't exist
• MetadataFetchError: When metadata cannot be retrieved

Example Usage

try {
  const descriptor = await MediaDescriptorFactory.fromManifestUrl(manifestUrl);

  // Access basic information
  console.log(descriptor.title);
  console.log(descriptor.manifestUrl);

  // Get available chapters
  const chapters = descriptor.chaptersEntries;

  // Get summary if available
  if (descriptor.summaryEntries.length > 0) {
    const summary = await descriptor.getSummary(descriptor.summaryEntries[0]);
    console.log(summary.abstract);
  }
} catch (error) {
  if (error instanceof VideoNotFoundError) {
    console.error("Video not found");
  }
}

Contributing

Contributions are welcome! Please read the contributing guidelines first.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• Documentation
• GitHub Issues