> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budgetpixel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embeds & oEmbed

> Embed BudgetPixel posts, sound effects and music tracks on any site — an oEmbed 1.0 endpoint with discovery tags, a registry listing, and a plain iframe snippet for editors that don't support oEmbed.

Public BudgetPixel content can be embedded on other websites. Two paths:

* **Paste the link.** Editors that support oEmbed — self-hosted WordPress (for admins/editors), Ghost, Discourse, Slack unfurls, Mastodon cards, and the iframely/embed.ly-backed editors behind Notion, Medium and Substack — turn a pasted `budgetpixel.com` link into the player automatically. BudgetPixel is listed in the [oEmbed providers registry](https://oembed.com/providers.json) and every embeddable page carries a discovery tag.
* **Copy the embed code.** The **Embed** button on post pages (share menu) and on every sound and music page copies the same snippet the oEmbed endpoint returns, for plain HTML sites and editors without oEmbed support.

## What can be embedded

| URL pattern                                       | Content                                 | Embed type            |
| ------------------------------------------------- | --------------------------------------- | --------------------- |
| `https://budgetpixel.com/p/{id}`                  | Public community posts (image or video) | `rich` / `video`      |
| `https://budgetpixel.com/sfx/{slug}`              | Free sound effects                      | `rich` (audio player) |
| `https://budgetpixel.com/background-music/{slug}` | Free background music                   | `rich` (audio player) |

Only **public, moderation-passed** posts are embeddable; private, unlisted, deleted or adult-rated posts return `404`. An embed always reflects the post's current state — if the creator deletes it later, the player shows an "unavailable" notice.

## Endpoint

```
GET https://budgetpixel.com/oembed?url={page url}&format=json[&maxwidth=][&maxheight=]
```

| Parameter   | Notes                                                                         |
| ----------- | ----------------------------------------------------------------------------- |
| `url`       | Required. URL-encoded page URL matching one of the patterns above.            |
| `format`    | `json` only. `xml` returns `501`.                                             |
| `maxwidth`  | Optional, 200–1200 px (default 600). Height follows the media's aspect ratio. |
| `maxheight` | Optional. The frame is scaled down to fit, keeping the aspect ratio.          |

Responses carry `Cache-Control: public, max-age=900` and `cache_age: 3600`. Unknown or non-public URLs return `404`.

### Example

```bash theme={null}
curl "https://budgetpixel.com/oembed?url=https%3A%2F%2Fbudgetpixel.com%2Fp%2F80503&format=json"
```

```json theme={null}
{
  "version": "1.0",
  "type": "rich",
  "provider_name": "BudgetPixel",
  "provider_url": "https://budgetpixel.com/",
  "title": "My Lenka, perfect beauty.",
  "author_name": "@standartis",
  "author_url": "https://budgetpixel.com/u/standartis",
  "width": 600,
  "height": 800,
  "thumbnail_url": "https://cdn.budgetpixel.com/posts/19627/thumb/….jpg",
  "thumbnail_width": 1728,
  "thumbnail_height": 2304,
  "cache_age": 3600,
  "html": "<iframe src=\"https://budgetpixel.com/embed/p/80503\" width=\"600\" height=\"800\" …></iframe><p class=\"bp-embed-caption\"><a href=\"https://budgetpixel.com/p/80503\">My Lenka, perfect beauty.</a> by <a href=\"https://budgetpixel.com/u/standartis\">@standartis</a> · <a href=\"https://budgetpixel.com/\">BudgetPixel</a></p>"
}
```

The `html` is an iframe of a bare embed page (`/embed/p/{id}`, `/embed/sfx/{slug}`, `/embed/music/{slug}`) plus a caption **outside** the frame naming the post, the creator and BudgetPixel. Embed pages set `Content-Security-Policy: frame-ancestors *` and `X-Robots-Tag: noindex`, contain no authenticated actions, and load no cookies or analytics.

## Discovery tag

Every embeddable page includes:

```html theme={null}
<link rel="alternate" type="application/json+oembed"
      href="https://budgetpixel.com/oembed?url=https%3A%2F%2Fbudgetpixel.com%2Fp%2F80503&format=json"
      title="…">
```

## Terms

Embedding public posts and Audio Library content is covered by the [Terms of Service](https://budgetpixel.com/terms) (Sections 9 and 21) and the [audio license](https://budgetpixel.com/audio-license). Embeds stream media from BudgetPixel; they are not downloads and do not grant additional rights.