Nostube Embed Player - Examples & Documentation

Parameter Reference

All parameters are passed via URL query string. Only the v parameter is required.

Parameter	Type	Default	Description
`v` REQUIRED	string	-	Video identifier in NIP-19 format: `nevent1...`, `naddr1...`, or `note1...`
`autoplay`	0 or 1	0	Auto-play video on load. Note: Most browsers require `muted=1` for autoplay to work
`muted`	0 or 1	0	Start video muted. Required for autoplay in most browsers
`loop`	0 or 1	0	Loop video playback continuously
`t`	number	0	Start time in seconds (e.g., `t=30` starts at 30 seconds)
`controls`	0 or 1	1	Show/hide native video controls (play, pause, volume, fullscreen)
`title`	0 or 1	1	Show/hide title overlay with video name and author
`branding`	0 or 1	1	Show/hide "Watch on Nostube" branding link in bottom-right corner
`quality`	string	auto	Preferred video quality: `1080p`, `720p`, `480p`, `360p`, or `auto`
`color`	hex	8b5cf6	Accent color for UI elements (without # prefix, e.g., `ff0000` for red)
`relays`	string	auto	Custom relay list (comma-separated WebSocket URLs). By default uses hint relays from the video identifier

💡 Usage Tips

Use autoplay=1&muted=1 together for reliable autoplay across browsers
Set title=0&branding=0 for a minimal, distraction-free player
Custom colors enhance brand consistency (e.g., match your site's theme)
Quality selection is automatic by default but can be forced for bandwidth considerations

Basic Examples

Common embedding scenarios to get you started quickly.

1. Default Player

All features enabled with default settings. Shows title overlay, branding, and native controls.

<iframe
  src="https://nostu.be/embed?v=nevent1qvzqqqqqz5q3jamnwvaz7tmgv9mx2m3wwdkxjer9wd68ytnwv46z7qpq8r5f947gp2tnxap68ew8dau6lmahwvta8rjgz4tplad4tefnph2sx9sssk"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

2. Autoplay (Muted)

Video starts playing automatically when loaded. Muted is required for autoplay to work in most browsers.

<iframe
  src="https://nostu.be/embed?v=nevent1qvzqqqqqz5q3jamnwvaz7tmgv9mx2m3wwdkxjer9wd68ytnwv46z7qpq8r5f947gp2tnxap68ew8dau6lmahwvta8rjgz4tplad4tefnph2sx9sssk&autoplay=1&muted=1"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

3. No Title Overlay

Hide the title overlay for a cleaner look. Branding link remains visible.

<iframe
  src="https://nostu.be/embed?v=nevent1qvzqqqqqz5q3jamnwvaz7tmgv9mx2m3wwdkxjer9wd68ytnwv46z7qpq8r5f947gp2tnxap68ew8dau6lmahwvta8rjgz4tplad4tefnph2sx9sssk&title=0"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

4. No Branding Link

Remove the "Watch on Nostube" link. Title overlay still displays.

<iframe
  src="https://nostu.be/embed?v=nevent1qvzqqqqqz5q3jamnwvaz7tmgv9mx2m3wwdkxjer9wd68ytnwv46z7qpq8r5f947gp2tnxap68ew8dau6lmahwvta8rjgz4tplad4tefnph2sx9sssk&branding=0"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

5. Start at Specific Time

Video starts playing from 30 seconds. Useful for highlighting specific moments.

<iframe
  src="https://nostu.be/embed?v=nevent1qvzqqqqqz5q3jamnwvaz7tmgv9mx2m3wwdkxjer9wd68ytnwv46z7qpq8r5f947gp2tnxap68ew8dau6lmahwvta8rjgz4tplad4tefnph2sx9sssk&t=30"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

6. Looping Video

Video automatically restarts when it reaches the end. Perfect for background videos or demos.

<iframe
  src="https://nostu.be/embed?v=nevent1qvzqqqqqz5q3jamnwvaz7tmgv9mx2m3wwdkxjer9wd68ytnwv46z7qpq8r5f947gp2tnxap68ew8dau6lmahwvta8rjgz4tplad4tefnph2sx9sssk&loop=1"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

Advanced Examples

Advanced configurations for specific use cases and custom branding requirements.

7. Minimal Player

Absolutely minimal player with all overlays disabled. Just the video and controls.

<iframe
  src="https://nostu.be/embed?v=nevent1qvzqqqqqz5q3jamnwvaz7tmgv9mx2m3wwdkxjer9wd68ytnwv46z7qpq8r5f947gp2tnxap68ew8dau6lmahwvta8rjgz4tplad4tefnph2sx9sssk&title=0&branding=0"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

8. Custom Red Theme

Custom accent color for branding. The "Watch on Nostube" link glows red on hover.

<iframe
  src="https://nostu.be/embed?v=nevent1qvzqqqqqz5q3jamnwvaz7tmgv9mx2m3wwdkxjer9wd68ytnwv46z7qpq8r5f947gp2tnxap68ew8dau6lmahwvta8rjgz4tplad4tefnph2sx9sssk&color=ff0000"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

9. Custom Blue Theme

Cyan/aqua accent color for a modern, vibrant look matching your brand colors.

<iframe
  src="https://nostu.be/embed?v=nevent1qvzqqqqqz5q3jamnwvaz7tmgv9mx2m3wwdkxjer9wd68ytnwv46z7qpq8r5f947gp2tnxap68ew8dau6lmahwvta8rjgz4tplad4tefnph2sx9sssk&color=00d4ff"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

10. Custom Orange Theme

Warm orange accent for an energetic, attention-grabbing player appearance.

<iframe
  src="https://nostu.be/embed?v=nevent1qvzqqqqqz5q3jamnwvaz7tmgv9mx2m3wwdkxjer9wd68ytnwv46z7qpq8r5f947gp2tnxap68ew8dau6lmahwvta8rjgz4tplad4tefnph2sx9sssk&color=ff6b35"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

11. Background Video

Perfect for background videos: autoplays, loops continuously, muted, no overlays.

<iframe
  src="https://nostu.be/embed?v=nevent1qvzqqqqqz5q3jamnwvaz7tmgv9mx2m3wwdkxjer9wd68ytnwv46z7qpq8r5f947gp2tnxap68ew8dau6lmahwvta8rjgz4tplad4tefnph2sx9sssk&autoplay=1&loop=1&muted=1&title=0&branding=0"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

12. Addressable Event (naddr)

Embedding an addressable video event using naddr format. Same features as nevent.

<iframe
  src="https://nostu.be/embed?v=naddr1qvzqqqy9hvpzp3yw98cykjpvcqw2r7003jrwlqcccpv7p6f4xg63vtcgpunwznq3qy88wumn8ghj7mn0wvhxcmmv9uqrk4rgv5k5wun9v96z6snfw33k76tw94qhwcttv4hxjmn894qk6etjd93kzm3dfphkgmpdg4exj6edgdshxmmw9568g6pkxsusmx2zsj"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

⚠️ Browser Autoplay Policies

Most modern browsers block autoplay with sound. Always use autoplay=1&muted=1 together for reliable autoplay. Users can unmute after the video starts playing.

Edge Cases & Error Handling

The embed player handles various error scenarios gracefully with user-friendly messages.

13. Invalid Video ID

When the video identifier format is invalid or malformed, an error message is displayed.

<iframe
  src="https://nostu.be/embed?v=invalid123"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

14. Missing Video ID

When the required v parameter is not provided, a clear error is shown.

<iframe
  src="https://nostu.be/embed"
  width="640"
  height="360"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>

📝 Error States

The embed player handles these error scenarios:

Missing or invalid video ID format
Video event not found on relays
Relay connection failures
Missing video URLs in event data
Video file loading errors

Interactive Embed Builder

Create custom embed codes with live preview. Adjust parameters and see changes in real-time.

Configuration

Video ID *

Autoplay

Muted

Loop

Start Time (seconds)

Show Controls

Show Title Overlay

Show Branding Link

Preferred Quality

Accent Color (hex without #)

Custom Relays (comma-separated, optional)

Iframe Width (px)

Iframe Height (px)

Live Preview

Embed Code

🔗 Direct Link

Best Practices

✅ Recommended Practices

Responsive Design: Use percentage widths (width="100%") and CSS for responsive embedding
Aspect Ratio: Maintain 16:9 aspect ratio (360p → 640×360, 720p → 1280×720)
Autoplay: Always combine autoplay=1 with muted=1 for browser compatibility
Accessibility: Provide text alternatives for embedded videos
Performance: Lazy-load embeds below the fold using loading="lazy"
Privacy: Nostube embeds don't track users or use cookies

⚠️ Common Pitfalls

Don't: Use autoplay without muted - browsers will block it
Don't: Set controls=0 without providing alternative controls
Don't: Embed dozens of autoplaying videos on one page - performance impact
Don't: Forget the allow attribute for autoplay/fullscreen

Responsive Embed Example (CSS)

/* Responsive 16:9 video container */
.video-container {
  position: relative;
  width: 100%;
  padding-bottom: 56.25%; /* 16:9 aspect ratio */
  height: 0;
  overflow: hidden;
}

.video-container iframe {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  border: none;
}

Lazy Loading Example (HTML)

<!-- Iframe loads only when visible -->
<iframe
  src="https://nostu.be/embed?v=nevent1..."
  width="640"
  height="360"
  frameborder="0"
  loading="lazy"
  allowfullscreen
  allow="autoplay; fullscreen">
</iframe>