Limitations
What ytcn cannot do, and why.
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.
Quality control
The YouTube IFrame API's setPlaybackQualityRange() is advisory, not imperative. YouTube uses DASH adaptive streaming, which automatically selects quality based on bandwidth, screen size, and device capabilities. You can request a quality level, but YouTube may ignore it.
For this reason, ytcn does not include quality controls. Displaying a quality selector that doesn't actually work would be dishonest. The video will play at the best quality YouTube deems appropriate.
Mobile browsers
| Limitation | Affected 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-none ignored | All 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 (signed-in users)
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.