A TypeScript oEmbed client library for fetching oEmbed data from various providers.
npm install @andrash/oembed-clientThis 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!
``bash`
npm install @andrash/oembed-clientor
yarn add @andrash/oembed-clientor
pnpm add @andrash/oembed-client
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:
`typescript
// 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.
Create an OembedClient instance, passing your provider configuration list to the constructor:
`typescript
import { OembedClient } from "@andrash/oembed-client";
import { OEMBED_PROVIDER_CONFIGS } from "./oembed-providers";
const oembedClient = new OembedClient(OEMBED_PROVIDER_CONFIGS);
`
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.
`typescript
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.");
}
You are now ready to use the oEmbed Client to fetch oEmbed data from various providers!