> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.podscan.fm/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Embedding Podcast Episodes from Podscan


This guide provides comprehensive documentation for embedding podcast episodes from Podscan using our embeddable player.

![](https://storage.crisp.chat/users/helpdesk/website/-/5/e/c/8/5ec8e994fe60b000/image_11lz127.png)

## Quick Start

The fastest way to embed a podcast episode is using an iframe with the episode's player URL:

```html
<iframe
    src="https://podscan.fm/player/ep_abc123xyz"
    width="100%"
    height="200"
    frameborder="0"
    allow="autoplay"
></iframe>
```

---

## URL Formats

Podscan supports three different URL patterns for accessing the player. **We recommend using encoded IDs for maximum stability and compatibility.**

### 1. Episode ID Only (Recommended)

**Format:** `/player/{episodeId}`

**Example:** `https://podscan.fm/player/ep_abc123xyz`

**Pros:**
* Shortest URL format
* Most stable (IDs never change)
* Recommended for API usage and embeds

**When to use:**
* API integrations
* Permanent embeds
* Programmatic access

### 2. Podcast + Episode IDs

**Format:** `/player/podcast/{podcastId}/episode/{episodeId}`

**Example:** `https://podscan.fm/player/podcast/pd_xyz789abc/episode/ep_abc123xyz`

**Pros:**
* Explicit podcast-episode relationship
* Good for API consumers who track both IDs

**When to use:**
* When you have both podcast and episode IDs
* Building navigation systems

### 3. Slug-Based URLs

**Format:** `/player/{podcastSlug}/{episodeSlug}`

**Example:** `https://podscan.fm/player/my-awesome-podcast/episode-42-the-answer`

**Pros:**
* Human-readable URLs
* SEO-friendly
* Better for sharing

**Cons:**
* Slugs can change if titles are updated
* Less stable than encoded IDs

**When to use:**
* Public-facing links
* Social media sharing
* Marketing materials

---

## ID System

Podscan uses stable identifiers for podcasts and episodes that never change, even if titles or other metadata are updated.

### ID Format

All IDs follow this pattern:
* **Podcasts:** `pd_` prefix (e.g., `pd_abc123xyz`)
* **Episodes:** `ep_` prefix (e.g., `ep_xyz789abc`)

### Why Use IDs Instead of Slugs?

1. **Stability:** IDs never change, even if episode/podcast metadata is updated
2. **Reliability:** Guaranteed to work permanently in embeds and integrations
3. **Consistency:** Standardized format across all API endpoints

### Where to Find IDs

You can obtain IDs through:
1. **Podscan API:** All API responses include IDs for podcasts and episodes
2. **Player Share URLs:** The player URL includes the episode ID
3. **Dashboard:** Episode and podcast page URLs contain their respective IDs

---

## Timestamp Navigation

The player supports deep-linking to specific timestamps in an episode. Add a timestamp parameter to any player URL to start playback at that point.

### Supported Parameters

The player accepts three equivalent parameter names:
* `?t=` (recommended, matches YouTube convention)
* `?time=`
* `?start=`

### Timestamp Formats

#### 1. Numeric Seconds (Simplest)

Start at 90 seconds:
```
https://podscan.fm/player/ep_abc123xyz?t=90
```

Decimals supported:
```
https://podscan.fm/player/ep_abc123xyz?t=90.5
```

#### 2. Seconds with Suffix

Start at 90 seconds:
```
https://podscan.fm/player/ep_abc123xyz?t=90s
```

#### 3. Milliseconds

Start at 90,000 milliseconds (90 seconds):
```
https://podscan.fm/player/ep_abc123xyz?t=90000ms
```

#### 4. Minutes and Seconds

Start at 1 minute, 30 seconds:
```
https://podscan.fm/player/ep_abc123xyz?t=1m30s
```

Just minutes:
```
https://podscan.fm/player/ep_abc123xyz?t=5m
```

#### 5. String Timestamps

Hours, minutes, seconds:
```
https://podscan.fm/player/ep_abc123xyz?t=1:23:45
```

Minutes and seconds:
```
https://podscan.fm/player/ep_abc123xyz?t=23:45
```

With decimals:
```
https://podscan.fm/player/ep_abc123xyz?t=1:23.5
```

### Timestamp Examples

| Format | URL Example | Starts At |
| ---- |
| `?t=90` | `/player/ep_abc?t=90` | 1 minute, 30 seconds |
| `?t=1:30` | `/player/ep_abc?t=1:30` | 1 minute, 30 seconds |
| `?t=1m30s` | `/player/ep_abc?t=1m30s` | 1 minute, 30 seconds |
| `?t=1:23:45` | `/player/ep_abc?t=1:23:45` | 1 hour, 23 minutes, 45 seconds |
| `?t=90s` | `/player/ep_abc?t=90s` | 1 minute, 30 seconds |
| `?t=90000ms` | `/player/ep_abc?t=90000ms` | 1 minute, 30 seconds |

### Bounds Checking

The player automatically:
* Clamps timestamps to valid range (0 to episode duration)
* Handles timestamps exceeding episode duration gracefully
* Defaults to start if timestamp parsing fails

---

## Customization Options

### URL Parameters

#### `t`, `time`, or `start` - Timestamp Navigation

Start playback at a specific timestamp. See [Timestamp Navigation](#timestamp-navigation) section for all supported formats.

```
https://podscan.fm/player/ep_abc?t=90
```

#### `autoplay` - Auto-Start Playback

Automatically start playback after the player loads (and seeks to timestamp if provided).

```
https://podscan.fm/player/ep_abc?autoplay=1
```

**Values:** `1` or `true`

**Default:** Off (no autoplay)

**Use case:**
* Direct play links
* Embedded players that should start immediately
* Combined with timestamp for auto-play from specific point

**Example with timestamp:**
```
https://podscan.fm/player/ep_abc?t=5m30s&autoplay=1
```

**⚠️ Browser Autoplay Policies:**

Modern browsers block autoplay with sound to protect user experience. Autoplay will only work if:
1. The user has previously interacted with the page/site
2. The site has been granted autoplay permissions by the browser
3. For iframes: The iframe has `allow="autoplay"` AND the parent page has had user interaction

If autoplay is blocked, the player will be ready at the specified timestamp, and the user can simply click the play button. This is normal browser behavior and not an error.

**For best results with embedded players:**
```html
<iframe
    src="https://podscan.fm/player/ep_abc?t=90&autoplay=1"
    allow="autoplay"
    ...
></iframe>
```

#### `embed` - Force Embedded Mode

Forces the player to render in embedded mode (removes margins, fills container).

```html
<iframe src="https://podscan.fm/player/ep_abc?embed=1"></iframe>
```

**Note:** The player automatically detects iframe context, so this parameter is usually unnecessary.

#### `nocache` - Bypass Cache

Forces the player to bypass cache and fetch fresh episode data.

```
https://podscan.fm/player/ep_abc?nocache=1
```

**Use case:** Testing updates to episode metadata immediately.

#### Combining Parameters

Use `&` to combine multiple parameters:

```
https://podscan.fm/player/ep_abc?t=90&autoplay=1
https://podscan.fm/player/ep_abc?t=5m30s&autoplay=1&nocache=1
```

---

## Embedded vs Standalone Mode

The player automatically adapts its layout depending on how it's accessed.

### Embedded Mode (iframe)

**Triggers:**
* Accessed within an iframe
* `?embed=1` parameter present
* Referer header indicates external site

**Features:**
* Compact player controls only
* No margins or padding
* Fills entire iframe container
* Minimal UI for space efficiency

**Recommended iframe size:**
* **Minimum height:** 200px
* **Recommended height:** 200-250px
* **Width:** 100% (responsive)

### Standalone Mode (Direct Access)

**Triggers:**
* Accessed directly in browser
* No iframe or embed parameter

**Features:**
* Full-page player interface
* Episode details and description
* Podcast information section
* Platform links (Apple Podcasts, Spotify, etc.)
* Rich metadata display

**Use case:**
* Shareable episode page
* Public episode landing page
* Direct episode access

---

## Complete Examples

### Basic Embed

```html
<iframe
    src="https://podscan.fm/player/ep_abc123xyz"
    width="100%"
    height="200"
    frameborder="0"
    allow="autoplay"
    loading="lazy"
></iframe>
```

### Embed with Timestamp

Start playback at 5 minutes, 30 seconds:

```html
<iframe
    src="https://podscan.fm/player/ep_abc123xyz?t=5m30s"
    width="100%"
    height="200"
    frameborder="0"
    allow="autoplay"
></iframe>
```

### Embed with Timestamp and Autoplay

Start playback at 5 minutes, 30 seconds and auto-play:

```html
<iframe
    src="https://podscan.fm/player/ep_abc123xyz?t=5m30s&autoplay=1"
    width="100%"
    height="200"
    frameborder="0"
    allow="autoplay"
></iframe>
```

### Responsive Embed Container

```html
<div style="position: relative; width: 100%; max-width: 800px; margin: 0 auto;">
    <iframe
        src="https://podscan.fm/player/ep_abc123xyz"
        width="100%"
        height="200"
        frameborder="0"
        allow="autoplay"
        style="border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);"
    ></iframe>
</div>
```

### Multiple Episodes Stacked

```html
<div style="max-width: 800px; margin: 0 auto; display: flex; flex-direction: column; gap: 20px;">
    <!-- Episode 1 -->
    <iframe
        src="https://podscan.fm/player/ep_episode1"
        width="100%"
        height="200"
        frameborder="0"
        allow="autoplay"
    ></iframe>

    <!-- Episode 2 -->
    <iframe
        src="https://podscan.fm/player/ep_episode2"
        width="100%"
        height="200"
        frameborder="0"
        allow="autoplay"
    ></iframe>
</div>
```

---

## Best Practices

### 1. Use Encoded IDs for Stability

Always prefer encoded episode IDs (`ep_xxx`) over slug-based URLs for embeds:

✅ **Good:** `https://podscan.fm/player/ep_abc123xyz`

❌ **Risky:** `https://podscan.fm/player/my-podcast/episode-title`

**Reason:** Encoded IDs are permanent, while slugs can change if episode titles are updated.

### 2. Set Appropriate iframe Dimensions

* **Minimum height:** 200px for full player controls
* **Recommended height:** 200-250px for optimal layout
* **Width:** Use `100%` for responsive design

### 3. Include `allow="autoplay"` Attribute

Some browsers require explicit permission for audio autoplay:

```html
<iframe allow="autoplay" ...></iframe>
```

### 4. Use Loading="lazy" for Performance

If embedding multiple players, lazy-load iframes below the fold:

```html
<iframe loading="lazy" ...></iframe>
```

### 5. Test Timestamps Thoroughly

When using timestamp parameters:
* Verify timestamps are within episode duration
* Test with different formats to ensure compatibility
* Use URL encoding for special characters if needed

### 6. Cache Considerations

The player aggressively caches episode data for 1 hour:
* Changes to episode metadata may take up to 1 hour to reflect
* Use `?nocache=1` during development/testing
* Avoid using `nocache` in production (performance impact)

### 7. Autoplay Considerations

Browser autoplay policies mean autoplay may not work in all situations:
* **Best for:** Embedded iframes on pages with user interaction
* **May not work:** Direct page loads without prior interaction
* **Always works:** User clicking the play button

Don't rely on autoplay as the only way to start playback. The player will be positioned at the correct timestamp, ready for the user to play.

### 8. Accessibility

For accessibility, provide context around embedded players:

```html
<div role="region" aria-label="Podcast Episode Player">
    <h3>Episode 42: The Answer to Everything</h3>
    <iframe
        src="https://podscan.fm/player/ep_abc123xyz"
        title="Podcast Episode: The Answer to Everything"
        width="100%"
        height="200"
        frameborder="0"
    ></iframe>
</div>
```

---

## Technical Details

### Player Features

* **Audio Format Support:** MP3, M4A, and other web-compatible formats
* **Playback Controls:** Play/pause, skip forward/back (30s/15s), speed control
* **Speed Options:** 0.5x, 0.75x, 1x, 1.25x, 1.5x, 1.75x, 2x
* **Volume Control:** Adjustable volume with mute option
* **Progress Tracking:** Draggable progress bar with hover preview
* **Share Functionality:** Native share API support with clipboard fallback

### Browser Compatibility

The player is compatible with:
* Chrome/Edge 90+
* Firefox 88+
* Safari 14+
* Mobile browsers (iOS Safari, Chrome Mobile)

### Performance

* **Caching:** 1-hour cache for episode metadata
* **CDN-Delivered:** Assets served via CDN for fast loading
* **Lazy Loading:** Audio loads on-demand (metadata preload)
* **Lightweight:** Minimal JavaScript footprint

---

## Getting Support

For issues or questions about embedding:

1. Check this documentation first
2. Visit [help.podscan.fm](https://help.podscan.fm)
3. Contact support through the dashboard