Limitations
Platform constraints and known limitations to be aware of before shipping.
Read before shipping
YouTube Terms of Service
Hiding YouTube branding may violate the YouTube API Terms of Service and Branding Guidelines. These documents require that the YouTube player be displayed "as provided" and prohibit modifications that obscure the YouTube logo. ytcn provides the tools — you are responsible for compliance with YouTube's terms.
Mobile Browsers
| Limitation | Platform | Details |
|---|---|---|
| Autoplay blocked | iOS, Android | Browser requires user interaction before playing audio. Muted autoplay usually works. |
| Native fullscreen | iOS Safari | Fullscreen opens the native video player. Custom controls are not visible. |
| Cursor hiding | Touch devices | Touch devices don't have a cursor. The idle controls cursor-hiding has no effect. |
| Volume control | iOS | iOS manages volume at the system level. The YouTube IFrame API volume methods have no effect. |
Caption Flash
YouTube automatically enables captions for signed-in users who have caption preferences set. ytcn calls unloadModule('captions') on every PLAYING event to suppress them. However, there may be a brief flash (under 200ms) before the suppression takes effect on initial play.
Private / Embeds-Disabled Videos
If a video is private or has embedding disabled:
- •Thumbnail probing fails →
thumbnailFailed = true - •ytcn skips the thumbnail phase and goes straight to iframe loading
- •The iframe may show a YouTube error message. Handle this via the YT error event.
SSR
All ytcn components use the "use client" directive. They do not render meaningful HTML on the server — the player is a client-side iframe. You can safely import them from Server Components without hydration errors.