Articles on: Automations & Integrations

Embedding Podcast Episodes from Podscan

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

Quick Start

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

<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?

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

Where to Find IDs

You can obtain IDs through:

Podscan API: All API responses include IDs for podcasts and episodes
Player Share URLs: The player URL includes the episode ID
Dashboard: Episode and podcast page URLs contain their respective IDs

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 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:

The user has previously interacted with the page/site
The site has been granted autoplay permissions by the browser
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:

<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).

<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

<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:

<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:

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

Responsive Embed Container

<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

<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:

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

4. Use Loading="lazy" for Performance

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

<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:

<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:

Check this documentation first
Visit help.podscan.fm
Contact support through the dashboard

Updated on: 24/10/2025

Was this article helpful?

Thank you!

Embedding Podcast Episodes from Podscan

Quick Start

URL Formats

1. Episode ID Only (Recommended)

2. Podcast + Episode IDs

3. Slug-Based URLs

ID System

ID Format

Why Use IDs Instead of Slugs?

Where to Find IDs

Timestamp Navigation

Supported Parameters

Timestamp Formats

1. Numeric Seconds (Simplest)

2. Seconds with Suffix

3. Milliseconds

4. Minutes and Seconds

5. String Timestamps

Timestamp Examples

Bounds Checking

Customization Options

URL Parameters

t, time, or start - Timestamp Navigation

autoplay - Auto-Start Playback

embed - Force Embedded Mode

nocache - Bypass Cache

Combining Parameters

Embedded vs Standalone Mode

Embedded Mode (iframe)

Standalone Mode (Direct Access)

Complete Examples

Basic Embed

Embed with Timestamp

Embed with Timestamp and Autoplay

Responsive Embed Container

Multiple Episodes Stacked

Best Practices

1. Use Encoded IDs for Stability

2. Set Appropriate iframe Dimensions

3. Include allow="autoplay" Attribute

4. Use Loading="lazy" for Performance

5. Test Timestamps Thoroughly

6. Cache Considerations

7. Autoplay Considerations

8. Accessibility

Technical Details

Player Features

Browser Compatibility

Performance

Getting Support

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

`autoplay` - Auto-Start Playback

`embed` - Force Embedded Mode

`nocache` - Bypass Cache

3. Include `allow="autoplay"` Attribute