oEmbed Client

This is a client library for fetching oEmbed information for media URLs from providers like YouTube, Twitter, and Instagram. It handles sending requests to oEmbed services and processing their JSON responses.

Note: This library only supports JSON responses and does not support XML.

中文版請見: oEmbed Client Documentation (Traditional Chinese)

Acknowledgements: This project has adopted and refactored parts of the code and concepts from @extractus/oembed-extractor. Without the contributions of that project's authors, this project would have been difficult to complete. Special thanks to them!

Sponsor: This project is sponsored by Havppen: Create your exclusive "online course platform" and monetize your knowledge now!

Installation

npm install @andrash/oembed-client
# or
yarn add @andrash/oembed-client
# or
pnpm add @andrash/oembed-client

Usage

1. Create a Provider Configuration

The OembedClient does not automatically load any default list of oEmbed service providers. You must first create a provider configuration list to pass to the OembedClient upon initialization.

Here is an example of how to define your provider configurations:

// filepath: oembed-providers.ts
import { ProviderConfig } from "@andrash/oembed-client";

export const OEMBED_PROVIDER_CONFIGS: ProviderConfig[] = [
  // Basic example
  {
    name: "YouTube",
    url: "https://www.youtube.com/",
    endpoints: [
      {
        patterns: [
          "https://*.youtube.com/watch*",
          "https://*.youtube.com/v/*",
          "https://youtu.be/*",
          "https://*.youtube.com/playlist?list=*",
          "https://youtube.com/playlist?list=*",
          "https://*.youtube.com/shorts*",
          "https://youtube.com/shorts*",
          "https://*.youtube.com/embed/*",
          "https://*.youtube.com/live*",
          "https://youtube.com/live*",
        ],
        url: "https://www.youtube.com/oembed",
      },
    ],
  },
  // Advanced example: oEmbed service requiring an access token
  {
    name: "Example",
    url: "https://example.com",
    endpoints: [
      {
        patterns: ["http://example.com/*/p/*", "http://www.example.com/*/p/*"],
        url: "https://graph.example.com/oembed",
        queryParams: {
          // Some oEmbed services (like Facebook, Instagram, Threads) require an access token to authenticate requests. You can add the relevant query parameters here.
          access_token: process.env.EXAMPLE_OEMBED_ACCESS_TOKEN,
          // You can also add other custom query parameters...
        },
        headers: {
          // Some oEmbed services may require authorization information in the headers.
          Authorization: `Bearer ${process.env.EXAMPLE_OEMBED_ACCESS_TOKEN}`,
          // You can also add other custom headers...
        },
      },
    ],
  },

  // Other oEmbed service endpoints...
];

You can copy the example provider list file from this package at oembed-provider.config.ts. It includes many common oEmbed providers and can be modified to suit your needs.

2. Initialize the OembedClient

Create an OembedClient instance, passing your provider configuration list to the constructor:

import { OembedClient } from "@andrash/oembed-client";
import { OEMBED_PROVIDER_CONFIGS } from "./oembed-providers";

const oembedClient = new OembedClient(OEMBED_PROVIDER_CONFIGS);

3. Fetch oEmbed Data

Use the findEndpoint() method to get the correct provider endpoint for a given URL. Then, call the extract() method on the endpoint to fetch the oEmbed data.

const url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
const endpoint = oembedClient.findEndpoint(url);

if (endpoint) {
  try {
    const oembedData = await endpoint.extract(url, {
      // You can pass extra parameters here, such as maxwidth and maxheight.
      // These will be merged with any `queryParams` in your provider config.
      // If a parameter exists in both, the value passed here takes precedence.
      maxwidth: 600,
      maxheight: 400,
    });
    console.log(oembedData);
  } catch (error) {
    console.error("Error fetching oEmbed data:", error);
  }
} else {
  console.log("No matching oEmbed provider found for the URL.");
}

That's it!

You are now ready to use the oEmbed Client to fetch oEmbed data from various providers!