android-youtube-player: a WebView wrapper for YouTube playback in Android apps

The gap left by Google's deprecated Android Player API

Google's own YouTube Android Player API is deprecated. The README states that it was historically not reliable and that Google now recommends embedding the IFrame Player API inside a WebView instead. android-youtube-player exists to make that recommendation usable: it wraps the IFrame Player API, which runs in a WebView, and exposes it as a native Java/Kotlin interface so an app does not have to talk to JavaScript directly.

The audience is Android developers who need to play YouTube content without leaving their app. The README frames the library as the main YouTube player library for Android now that the official API is gone, and lists apps including Tumblr, Flipkart, McDonald's, InShot Video Editor, Genius and reddit is fun as users. The repository is Kotlin, MIT licensed, and the last push on the default dev branch was on 2026-06-15, so it is not abandoned, but that is also three months before today and the most recent release, 13.0.0, dates from 2025-09-21. Expect a library that is maintained at a slow, release-driven pace rather than one that tracks every upstream change.

A second, separate concern the README addresses head-on: whether wrapping YouTube's player violates terms of service. Its answer is no, because the library uses YouTube's own web player rather than extracting streams.

How the WebView wrapper and the Chromecast sender fit together

The core module gives you YouTubePlayerView, a View you place in an Activity or Fragment. That view hosts the WebView running the IFrame Player API. You interact with it through a YouTubePlayer reference obtained from the view, and you subscribe to a YouTubePlayerListener to receive callbacks such as onReady and onStateChanged. State can also be read on demand or tracked continuously with YouTubePlayerTracker, which is the pattern to reach for when several parts of a screen need the current playback position or state without each registering its own listener.

Because the player is a WebView, the library's own UI is optional. It ships a DefaultPlayerUiController and reusable pieces such as YouTubePlayerSeekBar, FadeViewHelper and TimeUtilities, but the documentation includes a section on creating your own custom UI, which is the honest signal that the default controls are a starting point rather than a finished product. If your design needs a specific control layout, you will be writing that layer yourself.

The Chromecast support is a separate extension library with two halves. A sender module (chromecast-sender) runs in your app and hands the video to a Chromecast device. A receiver module (chromecast-receiver) is the web app that runs on the cast target. The repository also carries chromecast-sender-sample-app and core-sample-app, so both integration paths have a working reference in the tree. Note that the receiver is something you host; the README has a section on hosting the Chromecast receiver and a registration step, which means casting is not a drop-in feature.

Adding the dependency and getting a video on screen

The README's Download section splits into Core and Chromecast, and the Quick start section follows it. The repository carries a dependencies.gradle file at the top level, and the README's Download section is where the artifact coordinates live; read them there rather than copying a version number from an article, since the version changes between releases.

Once the dependency resolves, the view goes into a layout and you initialize it in code, passing a listener that receives the player reference in onReady. That callback is where you load a video, because the underlying web player is not ready before it fires. The README's Quick start section and the API documentation for YouTubePlayerListener show the listener shape.

The README also documents a utility for loading videos, which is worth checking before you write your own ID parsing, since YouTube IDs appear in several URL shapes. Two configuration points matter early. IFramePlayerOptions controls what the embedded player exposes (the README's FAQ uses the controls parameter as the starting point for removing unwanted views). Full screen is handled through the library's own documentation rather than being automatic. If the video never starts, the first thing to check is that the listener fired at all: onReady not firing means the WebView never finished loading the IFrame API.

Lifecycle, release, and the failure modes that bite in production

The README dedicates a section to releasing the YouTubePlayerView and another to a LifecycleObserver. That is not decoration. A WebView holding a player is a heavy object tied to a view hierarchy, and leaving it alive past the point where the screen is gone is the classic way this integration leaks. The library gives you the hook; it does not apply it for you.

The README also ties correctness to visibility: it advises playing videos only when the player is visible, and states that following the documentation makes the library handle this automatically. Playback started while the view is off screen is the case where a WebView-based player stops being a clean abstraction and starts being a terms-of-service question.

Background playback is the sharpest limitation. The README lists it under Useful info, alongside Hardware acceleration and minSdk, rather than as a supported feature. If your product is a music or podcast app whose core requirement is audio that continues with the screen off, this library is the wrong foundation, and the documentation's own placement of the topic says as much.

The FAQ section on workarounds is telling in a different way. Changing video quality, logging into a YouTube account, blocking ads, removing views the controls parameter cannot remove, and forcing subtitles hidden are all listed as workarounds, not configuration. Each one means reaching past the native interface into the web player's behaviour, and each one is the kind of thing that can break when YouTube changes its player. Treat anything in that list as fragile.

How it compares to ExoPlayer and to a plain WebView

The honest alternative for pure playback is ExoPlayer (now Media3), and the difference is not quality, it is what you are allowed to play. ExoPlayer is a general media player: you give it a media source, and it decodes it. It has no concept of YouTube as a service. To play YouTube content with it you would need stream URLs, which is exactly the path that runs into YouTube's terms. android-youtube-player avoids that entirely by not touching streams: it drives YouTube's own web player. If your content is your own video files or a licensed CDN, ExoPlayer is the right tool and this library is not.

The other alternative is doing the wrapper yourself: a WebView plus the IFrame Player API and your own JavaScript bridge. That is genuinely what this library is, so the comparison is about the cost of the bridge. You would get full control and no dependency. You would also reimplement the listener plumbing, the state tracker, the default UI controller, the full-screen handling, and the Chromecast sender and receiver, and you would own the compatibility work when the IFrame API changes. For a single screen with one video, the DIY route is defensible. For an app where playback is a real feature, the wrapper earns its place.

Against Google's deprecated Android Player API there is no real comparison left, since the README's position is that it is deprecated and unreliable. Migration is the only question, not selection.

Licence, releases and what an upgrade actually costs

The library is MIT licensed, which is permissive and imposes no copyleft obligation on your app. Two practical notes that are not legal advice: the licence covers this wrapper, not YouTube's player or content, and the README separately warns that your Play Store title and description should make clear your app has no affiliation with YouTube. That is a store-listing concern, not a licence term, but it belongs in the same checklist.

Upgrade cadence is visible in the releases: 13.0.0 on 2025-09-21, 12.1.2 on 2025-06-22, and 12.1.1 on 2024-09-25. A major version bump after a roughly three-month gap suggests the 13.x line carried breaking changes. The README does not document a rollback procedure, so pin your version and read the release notes before moving, rather than tracking a dynamic version.

The hidden upgrade cost is not the library's own API. It is the web player underneath. Anything you built on the FAQ workarounds (ad skipping, quality selection, account login, subtitle suppression) depends on YouTube's player behaviour, and the README presents those as workarounds precisely because they sit outside the supported interface. Budget for re-verifying them after any upgrade, including upgrades you did not make.

Editorial conclusion

Adopt android-youtube-player if you need YouTube playback inside an Android app and are willing to accept a WebView-based player, and add the Chromecast modules only if you actually cast. Do not adopt it if you need to play YouTube audio with the screen off, since the README points to its own workaround page for background playback rather than a supported mode, or if your app cannot show a visible player view while a video plays. Before shipping, verify that the player view is released on lifecycle teardown, check the minSdk value your build resolves, and confirm your Play Store listing does not imply affiliation with YouTube.

Frequently asked questions

Official sources

1. License: MIT
2. PierfrancescoSoffritti/android-youtube-player on GitHub
3. Project website
4. README
5. Releases