{"_id":"@capawesome/capacitor-youtube-player","_rev":"3-8baffa017e07204c0238f764eb065bbb","name":"@capawesome/capacitor-youtube-player","dist-tags":{"latest":"0.1.1"},"versions":{"0.0.1":{"name":"@capawesome/capacitor-youtube-player","version":"0.0.1","keywords":["capacitor","plugin","native","capacitor-plugin","youtube","youtube-player","video","player","embed","iframe"],"author":{"name":"Robin Genz","email":"mail@robingenz.dev"},"license":"MIT","_id":"@capawesome/capacitor-youtube-player@0.0.1","maintainers":[{"name":"robingenz","email":"mail@robingenz.dev"}],"homepage":"https://capawesome.io/docs/sdks/capacitor/youtube-player/","bugs":{"url":"https://github.com/capawesome-team/capacitor-plugins/issues"},"dist":{"shasum":"c05bd4d7576a20adb34800434a7be95b4028d3e9","tarball":"https://registry.npmjs.org/@capawesome/capacitor-youtube-player/-/capacitor-youtube-player-0.0.1.tgz","fileCount":86,"integrity":"sha512-OU+vf0rtNbVKteqXg7k0bcsuljjL04TWjiXj18+QbGyIjT1peUcOC4FBil1Pm0PkcL1+BQf7hveiP23aXgqhjA==","signatures":[{"sig":"MEYCIQDI5mzBB3b5N4VuB4MhYAnHvkMzO4YGsO9fZEB0bwSMmgIhAL+Y/E1FOL9wzrtPE93Ksj7uNsD+hafOlatwauMoC2fh","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":370772},"main":"dist/plugin.cjs.js","types":"dist/esm/index.d.ts","unpkg":"dist/plugin.js","module":"dist/esm/index.js","funding":[{"url":"https://github.com/sponsors/capawesome-team/","type":"github"},{"url":"https://opencollective.com/capawesome","type":"opencollective"}],"gitHead":"691c6a81b477efcb3ce937d7f80bb3d4fd1fe4a1","scripts":{"fmt":"npm run eslint -- --fix && npm run prettier -- --write && npm run swiftlint -- --fix --format","lint":"npm run eslint && npm run prettier -- --check && npm run swiftlint -- lint","build":"npm run clean && npm run docgen && tsc && rollup -c rollup.config.mjs","clean":"rimraf ./dist","watch":"tsc --watch","docgen":"docgen --api YoutubePlayerPlugin --output-readme README.md --output-json dist/docs.json","eslint":"eslint . --ext ts","verify":"npm run verify:ios && npm run verify:android && npm run verify:web","prettier":"prettier \"**/*.{css,html,ts,js,java}\"","swiftlint":"node-swiftlint","verify:ios":"cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS && cd ..","verify:web":"npm run build","prepublishOnly":"npm run build","verify:android":"cd android && ./gradlew clean build test && cd ..","ios:pod:install":"cd ios && pod install --repo-update && cd ..","ios:spm:install":"cd ios && swift package resolve && cd .."},"_npmUser":{"name":"robingenz","email":"mail@robingenz.dev"},"capacitor":{"ios":{"src":"ios"},"android":{"src":"android"}},"repository":{"url":"git+https://github.com/capawesome-team/capacitor-plugins.git","type":"git"},"_npmVersion":"11.13.0","description":"Capacitor plugin to embed and control YouTube players on Android, iOS, and Web.","directories":{},"_nodeVersion":"24.16.0","eslintConfig":{"extends":"@ionic/eslint-config/recommended"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"8.57.0","rimraf":"6.1.2","rollup":"4.53.3","swiftlint":"2.0.0","typescript":"5.9.3","@capacitor/cli":"8.0.0","@capacitor/ios":"8.0.0","@capacitor/core":"8.0.0","@capacitor/docgen":"0.3.1","@capacitor/android":"8.0.0","@ionic/eslint-config":"0.4.0","prettier-plugin-java":"2.6.7"},"peerDependencies":{"@capacitor/core":">=8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/capacitor-youtube-player_0.0.1_1783839261223_0.9396518644771688","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@capawesome/capacitor-youtube-player","version":"0.1.0","keywords":["capacitor","plugin","native","capacitor-plugin","youtube","youtube-player","video","player","embed","iframe"],"author":{"name":"Robin Genz","email":"mail@robingenz.dev"},"license":"MIT","_id":"@capawesome/capacitor-youtube-player@0.1.0","maintainers":[{"name":"robingenz","email":"mail@robingenz.dev"}],"homepage":"https://capawesome.io/docs/sdks/capacitor/youtube-player/","bugs":{"url":"https://github.com/capawesome-team/capacitor-plugins/issues"},"dist":{"shasum":"53b0aa23335a0361f8b5ddac42a0916ff458f5af","tarball":"https://registry.npmjs.org/@capawesome/capacitor-youtube-player/-/capacitor-youtube-player-0.1.0.tgz","fileCount":86,"integrity":"sha512-7nxp+Ppg4iEVZkhyOJSuJYhf89lwcb1hyJpFACkll79Bm2oJJQi8R/Z8zrGeXOHY8CLmX2Yzk2GjacRH56px5g==","signatures":[{"sig":"MEYCIQCYiQd+eHUBW0vQn9WZ+0Q9YrDAb3XKImJ5ri6hmmpYhQIhAJloulkP8SGKv8GVBu+9PXl1/n9hIjKndgRbTka7SKmW","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@capawesome%2fcapacitor-youtube-player@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":370772},"main":"dist/plugin.cjs.js","types":"dist/esm/index.d.ts","unpkg":"dist/plugin.js","module":"dist/esm/index.js","funding":[{"url":"https://github.com/sponsors/capawesome-team/","type":"github"},{"url":"https://opencollective.com/capawesome","type":"opencollective"}],"gitHead":"1ce17b1fd14c43b2f1d5d3c2da82221e1d1dca37","scripts":{"fmt":"npm run eslint -- --fix && npm run prettier -- --write && npm run swiftlint -- --fix --format","lint":"npm run eslint && npm run prettier -- --check && npm run swiftlint -- lint","build":"npm run clean && npm run docgen && tsc && rollup -c rollup.config.mjs","clean":"rimraf ./dist","watch":"tsc --watch","docgen":"docgen --api YoutubePlayerPlugin --output-readme README.md --output-json dist/docs.json","eslint":"eslint . --ext ts","verify":"npm run verify:ios && npm run verify:android && npm run verify:web","prettier":"prettier \"**/*.{css,html,ts,js,java}\"","swiftlint":"node-swiftlint","verify:ios":"cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS && cd ..","verify:web":"npm run build","prepublishOnly":"npm run build","verify:android":"cd android && ./gradlew clean build test && cd ..","ios:pod:install":"cd ios && pod install --repo-update && cd ..","ios:spm:install":"cd ios && swift package resolve && cd .."},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ab85ed57-a03e-41cb-a3ad-e1b82cf02654"}},"capacitor":{"ios":{"src":"ios"},"android":{"src":"android"}},"repository":{"url":"git+https://github.com/capawesome-team/capacitor-plugins.git","type":"git"},"_npmVersion":"11.16.0","description":"Capacitor plugin to embed and control YouTube players on Android, iOS, and Web.","directories":{},"_nodeVersion":"24.18.0","eslintConfig":{"extends":"@ionic/eslint-config/recommended"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"8.57.0","rimraf":"6.1.2","rollup":"4.53.3","swiftlint":"2.0.0","typescript":"5.9.3","@capacitor/cli":"8.0.0","@capacitor/ios":"8.0.0","@capacitor/core":"8.0.0","@capacitor/docgen":"0.3.1","@capacitor/android":"8.0.0","@ionic/eslint-config":"0.4.0","prettier-plugin-java":"2.6.7"},"peerDependencies":{"@capacitor/core":">=8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/capacitor-youtube-player_0.1.0_1784015620167_0.5048048645093277","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@capawesome/capacitor-youtube-player","version":"0.1.1","description":"Capacitor plugin to embed and control YouTube players on Android, iOS, and Web.","main":"dist/plugin.cjs.js","module":"dist/esm/index.js","types":"dist/esm/index.d.ts","unpkg":"dist/plugin.js","author":{"name":"Robin Genz","email":"mail@robingenz.dev"},"license":"MIT","homepage":"https://capawesome.io/docs/sdks/capacitor/youtube-player/","repository":{"type":"git","url":"git+https://github.com/capawesome-team/capacitor-plugins.git"},"bugs":{"url":"https://github.com/capawesome-team/capacitor-plugins/issues"},"funding":[{"type":"github","url":"https://github.com/sponsors/capawesome-team/"},{"type":"opencollective","url":"https://opencollective.com/capawesome"}],"keywords":["capacitor","plugin","native","capacitor-plugin","youtube","youtube-player","video","player","embed","iframe"],"scripts":{"verify":"npm run verify:ios && npm run verify:android && npm run verify:web","verify:ios":"cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS && cd ..","verify:android":"cd android && ./gradlew clean build test && cd ..","verify:web":"npm run build","lint":"npm run eslint && npm run prettier -- --check && npm run swiftlint -- lint","fmt":"npm run eslint -- --fix && npm run prettier -- --write && npm run swiftlint -- --fix --format","eslint":"eslint . --ext ts","prettier":"prettier \"**/*.{css,html,ts,js,java}\"","swiftlint":"node-swiftlint","docgen":"docgen --api YoutubePlayerPlugin --output-readme README.md --output-json dist/docs.json","build":"npm run clean && npm run docgen && tsc && rollup -c rollup.config.mjs","clean":"rimraf ./dist","watch":"tsc --watch","ios:pod:install":"cd ios && pod install --repo-update && cd ..","ios:spm:install":"cd ios && swift package resolve && cd ..","prepublishOnly":"npm run build"},"devDependencies":{"@capacitor/android":"8.0.0","@capacitor/cli":"8.4.2","@capacitor/core":"8.0.0","@capacitor/docgen":"0.3.1","@capacitor/ios":"8.0.0","@ionic/eslint-config":"0.4.0","eslint":"8.57.0","prettier-plugin-java":"2.9.7","rimraf":"6.1.2","rollup":"4.62.3","swiftlint":"2.0.0","typescript":"5.9.3"},"peerDependencies":{"@capacitor/core":">=8.0.0"},"eslintConfig":{"extends":"@ionic/eslint-config/recommended"},"capacitor":{"ios":{"src":"ios"},"android":{"src":"android"}},"publishConfig":{"access":"public"},"gitHead":"7c1937ed10b7de86ca2c1cdc3539a2735fd69a00","_id":"@capawesome/capacitor-youtube-player@0.1.1","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-ZqQdAD5tgl0haXUhMocioIja0BjaeBLWP8jJqIp59toddRAVzGP0ERnCI6uCvQ573BzJWVfsc73KKa471P3axg==","shasum":"056095000abe23d9fd679594ab4777e10b039207","tarball":"https://registry.npmjs.org/@capawesome/capacitor-youtube-player/-/capacitor-youtube-player-0.1.1.tgz","fileCount":86,"unpackedSize":370677,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@capawesome%2fcapacitor-youtube-player@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCXGpHvW9+IIiuVYKCwv+ubSPdbJZvhBuoJhN2dudZhOgIhAMAoRSMf2iK7AIepZXrurfRbNIhU/I1IoU2MNSIh2dSw"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ab85ed57-a03e-41cb-a3ad-e1b82cf02654"}},"directories":{},"maintainers":[{"name":"robingenz","email":"mail@robingenz.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/capacitor-youtube-player_0.1.1_1788337434846_0.17200474199430316"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-12T06:54:21.090Z","modified":"2026-09-02T08:23:55.380Z","0.0.1":"2026-07-12T06:54:21.362Z","0.1.0":"2026-07-14T07:53:40.312Z","0.1.1":"2026-09-02T08:23:54.983Z"},"bugs":{"url":"https://github.com/capawesome-team/capacitor-plugins/issues"},"author":{"name":"Robin Genz","email":"mail@robingenz.dev"},"license":"MIT","homepage":"https://capawesome.io/docs/sdks/capacitor/youtube-player/","keywords":["capacitor","plugin","native","capacitor-plugin","youtube","youtube-player","video","player","embed","iframe"],"repository":{"type":"git","url":"git+https://github.com/capawesome-team/capacitor-plugins.git"},"description":"Capacitor plugin to embed and control YouTube players on Android, iOS, and Web.","maintainers":[{"name":"robingenz","email":"mail@robingenz.dev"}],"readme":"# Capacitor YouTube Player Plugin\n\nUnofficial Capacitor plugin to embed and control [YouTube](https://www.youtube.com/) players on Android, iOS, and Web.[^1]\n\n
\n \n \"Deliver\n \n
\n\n## Features\n\nThe Capacitor YouTube Player plugin embeds YouTube videos as inline, frame-positioned players in your Capacitor app. Here are some of the key features:\n\n- 🖥️ **Cross-platform**: Supports Android, iOS, and Web.\n- 🎞️ **Inline Playback**: Embed players inline on all platforms, including iOS.\n- 🧩 **Multi-Instance**: Create and control multiple players at the same time by ID.\n- 📐 **Frame Positioning**: Position and resize players with CSS pixel frames and keep them in sync with your layout.\n- 🎛️ **Playback Controls**: Load, cue, play, pause, seek, mute, volume, and playback rate.\n- 📡 **Typed Events**: Listen for ready, state, time, rate, error, and fullscreen events with typed listeners.\n- 📜 **Terms Compliant**: Built on the official YouTube IFrame Player API with TOS-compliant plumbing (see [YouTube Terms of Service](#youtube-terms-of-service)).\n- 🤝 **Compatibility**: Works alongside the [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/) and [Screen Orientation](https://capawesome.io/docs/sdks/capacitor/screen-orientation/) plugins.\n- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.\n- 🔁 **Up-to-date**: Always supports the latest Capacitor version.\n\nMissing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!\n\n## Use Cases\n\nThe YouTube Player plugin is typically used wherever you want to embed YouTube videos in your app, for example:\n\n- **Media apps**: Embed trailers, music videos, or episodes inline in your content.\n- **Onboarding & help**: Show tutorial and how-to videos directly in your app.\n- **News & blogs**: Render YouTube embeds in articles with native playback performance.\n- **Education**: Build course screens with multiple video lessons on one page.\n\n## Compatibility\n\n| Plugin Version | Capacitor Version | Status |\n| -------------- | ----------------- | -------------- |\n| 0.x.x | >=8.x.x | Active support |\n\n## Installation\n\nYou can use our **AI-Assisted Setup** to install the plugin.\nAdd the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:\n\n```bash\nnpx skills add capawesome-team/skills --skill capacitor-plugins\n```\n\nThen use the following prompt:\n\n```\nUse the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-youtube-player` plugin in my project.\n```\n\nIf you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:\n\n```bash\nnpm install @capawesome/capacitor-youtube-player\nnpx cap sync\n```\n\n### Android\n\nOn Android, the plugin uses the [android-youtube-player](https://github.com/PierfrancescoSoffritti/android-youtube-player) library, an open-source wrapper around the official YouTube IFrame Player API.\n\n#### Variables\n\nThis plugin will use the following project variables (defined in your app's `variables.gradle` file):\n\n- `$androidYoutubePlayerVersion` version of `com.pierfrancescosoffritti.androidyoutubeplayer:core` (default: `13.0.0`)\n\n#### Permissions\n\nThe plugin automatically adds the `android.permission.ACCESS_NETWORK_STATE` permission to your app's manifest. It is used to recover the player when the network connection is lost and restored. No action is required on your part.\n\n### iOS\n\nOn iOS, the plugin uses the [YoutubePlayerView](https://github.com/mukeshydv/YoutubePlayerView) library, an open-source wrapper around the official YouTube IFrame Player API. It can be integrated via Swift Package Manager or CocoaPods. No additional configuration is required.\n\n### Web\n\nThe web implementation loads the [YouTube IFrame Player API](https://developers.google.com/youtube/iframe_api_reference) from YouTube at runtime. This requires an active network connection. If your app enforces a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), make sure to allow the YouTube domains (e.g. `https://www.youtube.com` for `script-src` and `frame-src`).\n\n## Configuration\n\nNo configuration required for this plugin.\n\n## Usage\n\nThe following examples show how to use the plugin.\n\n### Create a player\n\nMeasure a placeholder element in your layout and create a player at its position:\n\n```typescript\nimport { YoutubePlayer } from '@capawesome/capacitor-youtube-player';\n\nconst createPlayer = async () => {\n const rect = document\n .querySelector('#player-placeholder')\n .getBoundingClientRect();\n await YoutubePlayer.createPlayer({\n id: 'my-player',\n frame: {\n x: rect.x,\n y: rect.y,\n width: rect.width,\n height: rect.height,\n },\n videoId: 'dQw4w9WgXcQ',\n options: {\n mute: true,\n },\n });\n};\n```\n\n### Control playback\n\n```typescript\nimport { YoutubePlayer } from '@capawesome/capacitor-youtube-player';\n\nconst controlPlayback = async () => {\n await YoutubePlayer.play({ id: 'my-player' });\n await YoutubePlayer.seekTo({ id: 'my-player', seconds: 42 });\n await YoutubePlayer.setVolume({ id: 'my-player', volume: 50 });\n await YoutubePlayer.setPlaybackRate({ id: 'my-player', rate: 1.5 });\n await YoutubePlayer.pause({ id: 'my-player' });\n};\n```\n\n### Listen for events\n\n```typescript\nimport { YoutubePlayer } from '@capawesome/capacitor-youtube-player';\n\nconst addListeners = async () => {\n await YoutubePlayer.addListener('playerReady', event => {\n console.log('Player ready:', event.id);\n });\n await YoutubePlayer.addListener('playerStateChange', event => {\n console.log('Player state:', event.id, event.state);\n });\n await YoutubePlayer.addListener('playerError', event => {\n console.error('Player error:', event.id, event.code);\n });\n};\n```\n\n### Remove a player\n\n```typescript\nimport { YoutubePlayer } from '@capawesome/capacitor-youtube-player';\n\nconst removePlayer = async () => {\n await YoutubePlayer.removePlayer({ id: 'my-player' });\n};\n```\n\n## API\n\n\n\n* [`createPlayer(...)`](#createplayer)\n* [`cueVideo(...)`](#cuevideo)\n* [`getCurrentTime(...)`](#getcurrenttime)\n* [`getDuration(...)`](#getduration)\n* [`loadVideo(...)`](#loadvideo)\n* [`mute(...)`](#mute)\n* [`pause(...)`](#pause)\n* [`play(...)`](#play)\n* [`removePlayer(...)`](#removeplayer)\n* [`seekTo(...)`](#seekto)\n* [`setPlaybackRate(...)`](#setplaybackrate)\n* [`setPlayerFrame(...)`](#setplayerframe)\n* [`setVolume(...)`](#setvolume)\n* [`unmute(...)`](#unmute)\n* [`addListener('currentTimeChange', ...)`](#addlistenercurrenttimechange-)\n* [`addListener('fullscreenChange', ...)`](#addlistenerfullscreenchange-)\n* [`addListener('playbackRateChange', ...)`](#addlistenerplaybackratechange-)\n* [`addListener('playerError', ...)`](#addlistenerplayererror-)\n* [`addListener('playerReady', ...)`](#addlistenerplayerready-)\n* [`addListener('playerStateChange', ...)`](#addlistenerplayerstatechange-)\n* [`removeAllListeners()`](#removealllisteners)\n* [Interfaces](#interfaces)\n* [Type Aliases](#type-aliases)\n\n\n\n\n\n\n### createPlayer(...)\n\n```typescript\ncreatePlayer(options: CreatePlayerOptions) => Promise\n```\n\nCreate a new YouTube player.\n\nOn Android and iOS, the player is rendered as a native view that is\npositioned above the web view at the given frame. The frame is not\nscrolled with the web content. Use `setPlayerFrame(...)` to keep the\nframe in sync with your layout (see the README for a recipe).\n\nThe player must be at least 200×200 CSS pixels, as required by the\n[YouTube Terms of Service](https://developers.google.com/youtube/terms/required-minimum-functionality#embedded-player-size).\n\n| Param | Type |\n| ------------- | ------------------------------------------------------------------- |\n| **`options`** | CreatePlayerOptions |\n\n**Returns:** Promise<CreatePlayerResult>\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### cueVideo(...)\n\n```typescript\ncueVideo(options: CueVideoOptions) => Promise\n```\n\nLoad a video into the player without starting playback.\n\n| Param | Type |\n| ------------- | ----------------------------------------------------------- |\n| **`options`** | CueVideoOptions |\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### getCurrentTime(...)\n\n```typescript\ngetCurrentTime(options: GetCurrentTimeOptions) => Promise\n```\n\nGet the current playback time of the player.\n\nOn Android, the value is answered from the most recent value pushed by\nthe player (updated multiple times per second during playback).\n\n| Param | Type |\n| ------------- | ----------------------------------------------------------------------- |\n| **`options`** | GetCurrentTimeOptions |\n\n**Returns:** Promise<GetCurrentTimeResult>\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### getDuration(...)\n\n```typescript\ngetDuration(options: GetDurationOptions) => Promise\n```\n\nGet the duration of the currently loaded video.\n\nOn Android, the value is answered from the most recent value pushed by\nthe player.\n\n| Param | Type |\n| ------------- | ----------------------------------------------------------------- |\n| **`options`** | GetDurationOptions |\n\n**Returns:** Promise<GetDurationResult>\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### loadVideo(...)\n\n```typescript\nloadVideo(options: LoadVideoOptions) => Promise\n```\n\nLoad a video into the player and start playback.\n\n| Param | Type |\n| ------------- | ------------------------------------------------------------- |\n| **`options`** | LoadVideoOptions |\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### mute(...)\n\n```typescript\nmute(options: MuteOptions) => Promise\n```\n\nMute the player.\n\n| Param | Type |\n| ------------- | --------------------------------------------------- |\n| **`options`** | MuteOptions |\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### pause(...)\n\n```typescript\npause(options: PauseOptions) => Promise\n```\n\nPause playback.\n\n| Param | Type |\n| ------------- | ----------------------------------------------------- |\n| **`options`** | PauseOptions |\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### play(...)\n\n```typescript\nplay(options: PlayOptions) => Promise\n```\n\nStart or resume playback.\n\n| Param | Type |\n| ------------- | --------------------------------------------------- |\n| **`options`** | PlayOptions |\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### removePlayer(...)\n\n```typescript\nremovePlayer(options: RemovePlayerOptions) => Promise\n```\n\nRemove the player and release all its resources.\n\n| Param | Type |\n| ------------- | ------------------------------------------------------------------- |\n| **`options`** | RemovePlayerOptions |\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### seekTo(...)\n\n```typescript\nseekTo(options: SeekToOptions) => Promise\n```\n\nSeek to the given time.\n\n| Param | Type |\n| ------------- | ------------------------------------------------------- |\n| **`options`** | SeekToOptions |\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### setPlaybackRate(...)\n\n```typescript\nsetPlaybackRate(options: SetPlaybackRateOptions) => Promise\n```\n\nSet the playback rate of the player.\n\n| Param | Type |\n| ------------- | ------------------------------------------------------------------------- |\n| **`options`** | SetPlaybackRateOptions |\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### setPlayerFrame(...)\n\n```typescript\nsetPlayerFrame(options: SetPlayerFrameOptions) => Promise\n```\n\nUpdate the frame of the player.\n\nCall this method whenever the layout changes (e.g. on scroll, resize or\norientation change) to keep the player in sync with your layout.\n\n| Param | Type |\n| ------------- | ----------------------------------------------------------------------- |\n| **`options`** | SetPlayerFrameOptions |\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### setVolume(...)\n\n```typescript\nsetVolume(options: SetVolumeOptions) => Promise\n```\n\nSet the volume of the player.\n\nOn iOS, the operating system does not allow changing the volume\nprogrammatically, so this method has no effect. Use `mute()` and\n`unmute()` instead.\n\n| Param | Type |\n| ------------- | ------------------------------------------------------------- |\n| **`options`** | SetVolumeOptions |\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### unmute(...)\n\n```typescript\nunmute(options: UnmuteOptions) => Promise\n```\n\nUnmute the player.\n\n| Param | Type |\n| ------------- | ------------------------------------------------------- |\n| **`options`** | UnmuteOptions |\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### addListener('currentTimeChange', ...)\n\n```typescript\naddListener(eventName: 'currentTimeChange', listenerFunc: (event: CurrentTimeChangeEvent) => void) => Promise\n```\n\nCalled when the current playback time of a player changes.\n\nThe event is emitted multiple times per second during playback. The\nexact frequency depends on the platform.\n\n| Param | Type |\n| ------------------ | --------------------------------------------------------------------------------------------- |\n| **`eventName`** | 'currentTimeChange' |\n| **`listenerFunc`** | (event: CurrentTimeChangeEvent) => void |\n\n**Returns:** Promise<PluginListenerHandle>\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### addListener('fullscreenChange', ...)\n\n```typescript\naddListener(eventName: 'fullscreenChange', listenerFunc: (event: FullscreenChangeEvent) => void) => Promise\n```\n\nCalled when a player enters or exits fullscreen.\n\nOnly available on Android and Web.\n\n| Param | Type |\n| ------------------ | ------------------------------------------------------------------------------------------- |\n| **`eventName`** | 'fullscreenChange' |\n| **`listenerFunc`** | (event: FullscreenChangeEvent) => void |\n\n**Returns:** Promise<PluginListenerHandle>\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### addListener('playbackRateChange', ...)\n\n```typescript\naddListener(eventName: 'playbackRateChange', listenerFunc: (event: PlaybackRateChangeEvent) => void) => Promise\n```\n\nCalled when the playback rate of a player changes.\n\nOn iOS, this event is only emitted for `setPlaybackRate(...)` calls.\n\n| Param | Type |\n| ------------------ | ----------------------------------------------------------------------------------------------- |\n| **`eventName`** | 'playbackRateChange' |\n| **`listenerFunc`** | (event: PlaybackRateChangeEvent) => void |\n\n**Returns:** Promise<PluginListenerHandle>\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### addListener('playerError', ...)\n\n```typescript\naddListener(eventName: 'playerError', listenerFunc: (event: PlayerErrorEvent) => void) => Promise\n```\n\nCalled when an error occurs in a player.\n\n| Param | Type |\n| ------------------ | --------------------------------------------------------------------------------- |\n| **`eventName`** | 'playerError' |\n| **`listenerFunc`** | (event: PlayerErrorEvent) => void |\n\n**Returns:** Promise<PluginListenerHandle>\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### addListener('playerReady', ...)\n\n```typescript\naddListener(eventName: 'playerReady', listenerFunc: (event: PlayerReadyEvent) => void) => Promise\n```\n\nCalled when a player has finished loading and is ready to receive\ncommands.\n\n| Param | Type |\n| ------------------ | --------------------------------------------------------------------------------- |\n| **`eventName`** | 'playerReady' |\n| **`listenerFunc`** | (event: PlayerReadyEvent) => void |\n\n**Returns:** Promise<PluginListenerHandle>\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### addListener('playerStateChange', ...)\n\n```typescript\naddListener(eventName: 'playerStateChange', listenerFunc: (event: PlayerStateChangeEvent) => void) => Promise\n```\n\nCalled when the state of a player changes.\n\n| Param | Type |\n| ------------------ | --------------------------------------------------------------------------------------------- |\n| **`eventName`** | 'playerStateChange' |\n| **`listenerFunc`** | (event: PlayerStateChangeEvent) => void |\n\n**Returns:** Promise<PluginListenerHandle>\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### removeAllListeners()\n\n```typescript\nremoveAllListeners() => Promise\n```\n\nRemove all listeners for this plugin.\n\n**Since:** 0.1.0\n\n--------------------\n\n\n### Interfaces\n\n\n#### CreatePlayerResult\n\n| Prop | Type | Description | Since |\n| -------- | ------------------- | -------------------------------------------- | ----- |\n| **`id`** | string | The unique identifier of the created player. | 0.1.0 |\n\n\n#### CreatePlayerOptions\n\n| Prop | Type | Description | Since |\n| ------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |\n| **`frame`** | PlayerFrame | The frame of the player in CSS pixels, relative to the viewport. Must be at least 200×200 CSS pixels. | 0.1.0 |\n| **`id`** | string | The unique identifier of the player. If not provided, a random identifier is generated. | 0.1.0 |\n| **`options`** | PlayerOptions | The player options. | 0.1.0 |\n| **`videoId`** | string | The ID of the YouTube video to load into the player. If not provided, the player is created without a video. Load one with `loadVideo(...)` or `cueVideo(...)`. | 0.1.0 |\n| **`web`** | CreatePlayerWebOptions | Options that are only available on Web. | 0.1.0 |\n\n\n#### PlayerFrame\n\nThe frame of a player in CSS pixels, relative to the viewport.\n\n| Prop | Type | Description | Since |\n| ------------ | ------------------- | --------------------------------------------------------------- | ----- |\n| **`height`** | number | The height of the player in CSS pixels. Must be at least `200`. | 0.1.0 |\n| **`width`** | number | The width of the player in CSS pixels. Must be at least `200`. | 0.1.0 |\n| **`x`** | number | The x-coordinate of the player in CSS pixels. | 0.1.0 |\n| **`y`** | number | The y-coordinate of the player in CSS pixels. | 0.1.0 |\n\n\n#### PlayerOptions\n\n| Prop | Type | Description | Default | Since |\n| ------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |\n| **`autoplay`** | boolean | Whether the video starts playing automatically when the player is created. | false | 0.1.0 |\n| **`ccLoadPolicy`** | boolean | Whether closed captions are shown by default, even if the user has turned captions off. | false | 0.1.0 |\n| **`controls`** | boolean | Whether the player controls are displayed. | true | 0.1.0 |\n| **`end`** | number | The time in seconds at which the player should stop playing the video. | | 0.1.0 |\n| **`fullscreen`** | boolean | Whether the fullscreen button is displayed. Only available on Android and Web. | false | 0.1.0 |\n| **`ivLoadPolicy`** | boolean | Whether video annotations are shown by default. | false | 0.1.0 |\n| **`mute`** | boolean | Whether the player is muted when it is created. | false | 0.1.0 |\n| **`rel`** | boolean | Whether related videos from other channels are shown when playback ends. If `false`, related videos are limited to the video's channel. | false | 0.1.0 |\n| **`start`** | number | The time in seconds from which the video should start playing. | | 0.1.0 |\n\n\n#### CreatePlayerWebOptions\n\n| Prop | Type | Description | Since |\n| --------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |\n| **`elementId`** | string | The ID of an existing DOM element to mount the player into. If provided, the player fills this element instead of being positioned at the given frame, and `setPlayerFrame(...)` has no effect. Only available on Web. | 0.1.0 |\n\n\n#### CueVideoOptions\n\n| Prop | Type | Description | Default | Since |\n| ------------------ | ------------------- | -------------------------------------------------------------------------------- | -------------- | ----- |\n| **`id`** | string | The unique identifier of the player. | | 0.1.0 |\n| **`startSeconds`** | number | The time in seconds from which the video should start playing once it is played. | 0 | 0.1.0 |\n| **`videoId`** | string | The ID of the YouTube video to cue. | | 0.1.0 |\n\n\n#### GetCurrentTimeResult\n\n| Prop | Type | Description | Since |\n| ----------------- | ------------------- | ------------------------------------- | ----- |\n| **`currentTime`** | number | The current playback time in seconds. | 0.1.0 |\n\n\n#### GetCurrentTimeOptions\n\n| Prop | Type | Description | Since |\n| -------- | ------------------- | ------------------------------------ | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n\n\n#### GetDurationResult\n\n| Prop | Type | Description | Since |\n| -------------- | ------------------- | ----------------------------------------------------------------------------------------- | ----- |\n| **`duration`** | number | The duration of the currently loaded video in seconds. Returns `0` if no video is loaded. | 0.1.0 |\n\n\n#### GetDurationOptions\n\n| Prop | Type | Description | Since |\n| -------- | ------------------- | ------------------------------------ | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n\n\n#### LoadVideoOptions\n\n| Prop | Type | Description | Default | Since |\n| ------------------ | ------------------- | -------------------------------------------------------------- | -------------- | ----- |\n| **`id`** | string | The unique identifier of the player. | | 0.1.0 |\n| **`startSeconds`** | number | The time in seconds from which the video should start playing. | 0 | 0.1.0 |\n| **`videoId`** | string | The ID of the YouTube video to load. | | 0.1.0 |\n\n\n#### MuteOptions\n\n| Prop | Type | Description | Since |\n| -------- | ------------------- | ------------------------------------ | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n\n\n#### PauseOptions\n\n| Prop | Type | Description | Since |\n| -------- | ------------------- | ------------------------------------ | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n\n\n#### PlayOptions\n\n| Prop | Type | Description | Since |\n| -------- | ------------------- | ------------------------------------ | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n\n\n#### RemovePlayerOptions\n\n| Prop | Type | Description | Since |\n| -------- | ------------------- | ------------------------------------ | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n\n\n#### SeekToOptions\n\n| Prop | Type | Description | Since |\n| ------------- | ------------------- | ------------------------------------ | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n| **`seconds`** | number | The time in seconds to seek to. | 0.1.0 |\n\n\n#### SetPlaybackRateOptions\n\n| Prop | Type | Description | Since |\n| ---------- | ------------------- | ------------------------------------------------------------------------------------------- | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n| **`rate`** | number | The playback rate. Must be one of `0.25`, `0.5`, `0.75`, `1`, `1.25`, `1.5`, `1.75` or `2`. | 0.1.0 |\n\n\n#### SetPlayerFrameOptions\n\n| Prop | Type | Description | Since |\n| ----------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----- |\n| **`frame`** | PlayerFrame | The new frame of the player in CSS pixels, relative to the viewport. Must be at least 200×200 CSS pixels. | 0.1.0 |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n\n\n#### SetVolumeOptions\n\n| Prop | Type | Description | Since |\n| ------------ | ------------------- | -------------------------------------------- | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n| **`volume`** | number | The volume as a value between `0` and `100`. | 0.1.0 |\n\n\n#### UnmuteOptions\n\n| Prop | Type | Description | Since |\n| -------- | ------------------- | ------------------------------------ | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n\n\n#### PluginListenerHandle\n\n| Prop | Type |\n| ------------ | ----------------------------------------- |\n| **`remove`** | () => Promise<void> |\n\n\n#### CurrentTimeChangeEvent\n\n| Prop | Type | Description | Since |\n| ----------------- | ------------------- | ------------------------------------- | ----- |\n| **`currentTime`** | number | The current playback time in seconds. | 0.1.0 |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n\n\n#### FullscreenChangeEvent\n\n| Prop | Type | Description | Since |\n| ---------------- | -------------------- | ------------------------------------ | ----- |\n| **`fullscreen`** | boolean | Whether the player is in fullscreen. | 0.1.0 |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n\n\n#### PlaybackRateChangeEvent\n\n| Prop | Type | Description | Since |\n| ---------- | ------------------- | ------------------------------------ | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n| **`rate`** | number | The new playback rate. | 0.1.0 |\n\n\n#### PlayerErrorEvent\n\n| Prop | Type | Description | Since |\n| ---------- | ----------------------------------------------------------- | ------------------------------------ | ----- |\n| **`code`** | PlayerErrorCode | The error code. | 0.1.0 |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n\n\n#### PlayerReadyEvent\n\n| Prop | Type | Description | Since |\n| -------- | ------------------- | ------------------------------------ | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n\n\n#### PlayerStateChangeEvent\n\n| Prop | Type | Description | Since |\n| ----------- | --------------------------------------------------- | ------------------------------------ | ----- |\n| **`id`** | string | The unique identifier of the player. | 0.1.0 |\n| **`state`** | PlayerState | The new state of the player. | 0.1.0 |\n\n\n### Type Aliases\n\n\n#### PlayerErrorCode\n\nThe error code of a player error.\n\n'html5-error' | 'invalid-parameter' | 'not-embeddable' | 'unknown' | 'video-not-found'\n\n\n#### PlayerState\n\nThe state of a player.\n\n'buffering' | 'cued' | 'ended' | 'paused' | 'playing' | 'unstarted'\n\n\n\n## Frame Synchronization\n\nOn Android and iOS, the player is a native view that is rendered **above** the web view. It is not part of the DOM and therefore does not scroll or resize with your web content. Instead, you position it with CSS pixel frames and keep it in sync with your layout by calling `setPlayerFrame(...)` whenever the layout changes:\n\n```typescript\nimport { YoutubePlayer } from '@capawesome/capacitor-youtube-player';\n\nconst syncPlayerFrame = async () => {\n const rect = document\n .querySelector('#player-placeholder')\n .getBoundingClientRect();\n await YoutubePlayer.setPlayerFrame({\n id: 'my-player',\n frame: {\n x: rect.x,\n y: rect.y,\n width: rect.width,\n height: rect.height,\n },\n });\n};\n\nwindow.addEventListener('scroll', syncPlayerFrame);\nwindow.addEventListener('resize', syncPlayerFrame);\n```\n\nIf you use a framework with its own scroll container (e.g. `ion-content`), attach the listener to that container's scroll event instead. On the Web, the player is positioned with `position: fixed`, so the same synchronization code works on all platforms. Alternatively, on the Web you can mount the player into an existing DOM element using the `web.elementId` option, in which case no frame synchronization is needed.\n\nSince the player is rendered above the web view, HTML content can never overlap the player. Keep this in mind when designing your layout (see also [YouTube Terms of Service](#youtube-terms-of-service)).\n\n## YouTube Terms of Service\n\nBy using this plugin, you agree to the [YouTube Terms of Service](https://www.youtube.com/t/terms) and the [YouTube API Services Terms of Service](https://developers.google.com/youtube/terms/api-services-terms-of-service). The plugin is designed to make it easy to comply with the [required minimum functionality](https://developers.google.com/youtube/terms/required-minimum-functionality) for embedded players:\n\n- **Minimum player size**: Embedded players must be at least 200×200 pixels. The plugin enforces this and rejects smaller frames with the `FRAME_INVALID` error code.\n- **No background playback**: Videos must not play in the background. The plugin automatically pauses all players when the app is moved to the background.\n- **No overlays**: The player (including its ads) must not be obscured by other content. Since the native player view is always rendered above the web view, HTML content cannot overlap it by design.\n- **Correct origin**: The plugin sets the `origin` player parameter correctly on all platforms, which avoids embed errors (e.g. error 152/153) without any header workarounds.\n- **No player modification**: The plugin embeds the official YouTube player unaltered. Your app must not modify, build upon, or block any portion or functionality of the player — including any ads it serves.\n- **Branding**: If your app displays YouTube logos or other brand assets alongside the player, follow the [YouTube Branding Guidelines](https://developers.google.com/youtube/terms/branding-guidelines).\n\n## Platform Support\n\nNot every feature is available on all platforms. The following table lists the per-platform differences of the plugin's API:\n\n| Feature | Android | iOS | Web |\n| ---------------------------------- | :-----: | :-: | :-: |\n| Playback controls | ✅ | ✅ | ✅ |\n| `fullscreen` option | ✅ | ❌ | ✅ |\n| `fullscreenChange` event | ✅ | ❌ | ✅ |\n| Native mute | ✅ | 🔄 | ✅ |\n\nAdditional platform-specific behavior:\n\n- **iOS mute emulation**: The iOS player library exposes no native mute API, so `mute()` is emulated by setting the volume to `0`. `unmute()` restores the last volume set via `setVolume(...)` (or `100`). If `setVolume(...)` is called while the player is muted, the volume is only applied on the next `unmute()` call.\n- **iOS playback rate event**: On iOS, the `playbackRateChange` event is only emitted for `setPlaybackRate(...)` calls, since the iOS player library exposes no playback rate callback.\n- **iOS error mapping**: On iOS, videos that are not allowed to be played in embedded players may be reported with the error code `unknown` instead of `not-embeddable`, due to the error mapping of the iOS player library.\n- **Android getters**: On Android, `getCurrentTime(...)` and `getDuration(...)` are answered from the most recent values pushed by the player, which are updated multiple times per second during playback.\n- **`currentTimeChange` frequency**: The event is emitted about 10 times per second on Android and about twice per second on iOS and Web.\n\n## FAQ\n\n### How is this plugin different from other similar plugins?\n\nThis plugin can render multiple native player instances at once, each positioned to an exact frame that you keep in sync with your layout. It exposes a full, strongly typed event set on Android, iOS, and Web, and embeds the official YouTube player unaltered. It is built to comply with the behaviors the YouTube Terms of Service require — a minimum player size, no background playback, nothing drawn over the player, and a correct origin — so you stay compliant by default. It is actively maintained and backed by dedicated support.\n\n### Why is my frame rejected with `FRAME_INVALID`?\n\nEmbedded YouTube players must be at least 200×200 CSS pixels, as required by the YouTube Terms of Service. Make sure the `width` and `height` of your frame are at least `200`.\n\n### Why does the player not scroll with my content?\n\nOn Android and iOS, the player is a native view rendered above the web view and is not part of the DOM. Use `setPlayerFrame(...)` to keep it in sync with your layout (see [Frame Synchronization](#frame-synchronization)).\n\n### Can I display HTML content above the player?\n\nNo. The native player view is always rendered above the web view. This is also a requirement of the YouTube Terms of Service, which prohibit obscuring the player.\n\n### Does playback continue in the background?\n\nNo. The YouTube Terms of Service prohibit background playback, so the plugin automatically pauses all players when the app is moved to the background.\n\n### Can I use this plugin with Ionic, React, Vue or Angular?\n\nYes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.\n\n## Related Plugins\n\n- [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/): Interact with media controllers, volume keys and media buttons.\n- [Screen Orientation](https://capawesome.io/docs/sdks/capacitor/screen-orientation/): Lock and unlock the screen orientation, for example to allow landscape playback.\n\n## Newsletter\n\nStay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).\n\n## Changelog\n\nSee [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/youtube-player/CHANGELOG.md).\n\n## License\n\nSee [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/youtube-player/LICENSE).\n\n[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or YouTube LLC or any of their affiliates or subsidiaries. \"YouTube\" is a trademark of Google LLC.\n","readmeFilename":"README.md"}