YouTubeUrlParser: Parse YouTube and YouTube Music URLs

YouTubeUrlParser is a Kotlin object utility for recognizing and extracting identifiers from YouTube and YouTube Music URLs. It returns typed ParsedUrl sealed class results so you can dispatch on the type of content the URL points to without manual string parsing.

`object YouTubeUrlParser`

`ParsedUrl` — Sealed Class

ParsedUrl is the return type of parse(). It has two concrete subtypes.

`ParsedUrl.Video`

data class Video(override val id: String) : ParsedUrl()

Represents a YouTube video URL. id is the 11-character YouTube video ID.

`ParsedUrl.Artist`

data class Artist(override val id: String) : ParsedUrl()

Represents a YouTube Music artist or channel URL. id is the channel browse ID (e.g. UCxxxxxx) or an album/artist browse ID (e.g. MPRExxxxxx).

`YouTubeUrlParser.parse(url: String): ParsedUrl?`

fun parse(url: String): ParsedUrl?

Parses a YouTube URL and returns the typed result, or null if the URL is not recognized. Supported video URL patterns:

Pattern	Example
YouTube Music watch URL	`https://music.youtube.com/watch?v=VIDEO_ID`
YouTube watch URL	`https://www.youtube.com/watch?v=VIDEO_ID`
Short link	`https://youtu.be/VIDEO_ID`
YouTube Shorts	`https://www.youtube.com/shorts/VIDEO_ID`

Supported artist URL patterns (music.youtube.com only):

Pattern	Example
Channel URL	`https://music.youtube.com/channel/UCxxxxxx`
Browse URL (album/artist)	`https://music.youtube.com/browse/MPRExxxxxxxx`

Artist URL matching is restricted to music.youtube.com domains. Standard youtube.com/channel/... URLs are not matched as artists.

`YouTubeUrlParser.isYouTubeUrl(text: String): Boolean`

fun isYouTubeUrl(text: String): Boolean

Returns true if the text is a recognized YouTube or YouTube Music URL (i.e. parse() would return a non-null result). Useful for detecting URLs pasted by users.

val isPasted = YouTubeUrlParser.isYouTubeUrl(clipboardText)

`YouTubeUrlParser.extractVideoId(url: String): String?`

fun extractVideoId(url: String): String?

Convenience function. Returns the video ID string if url is a video URL, or null for artist URLs and unrecognized inputs. Equivalent to:

(YouTubeUrlParser.parse(url) as? YouTubeUrlParser.ParsedUrl.Video)?.id

`YouTubeUrlParser.createWatchEndpoint(url: String): WatchEndpoint?`

fun createWatchEndpoint(url: String): WatchEndpoint?

Creates a WatchEndpoint(videoId = ...) from a video URL. Returns null if the URL is not a video URL. Useful for passing directly to YouTube.next() or YouTube.player().

val endpoint = YouTubeUrlParser.createWatchEndpoint("https://music.youtube.com/watch?v=dQw4w9WgXcQ")
// WatchEndpoint(videoId = "dQw4w9WgXcQ")

Usage Examples

Handling a Shared URL

fun handleSharedUrl(url: String) {
    when (val parsed = YouTubeUrlParser.parse(url)) {
        is YouTubeUrlParser.ParsedUrl.Video -> {
            // Launch playback
            val endpoint = WatchEndpoint(videoId = parsed.id)
            coroutineScope.launch {
                val nextResult = YouTube.next(endpoint).getOrNull()
                // start player with nextResult
            }
        }
        is YouTubeUrlParser.ParsedUrl.Artist -> {
            // Navigate to artist page
            coroutineScope.launch {
                val artistPage = YouTube.artist(parsed.id).getOrNull()
                // show artistPage
            }
        }
        null -> {
            // Not a YouTube URL — handle as plain search query or ignore
        }
    }
}

Detecting YouTube URLs in User Input

val userInput = binding.searchInput.text.toString().trim()

if (YouTubeUrlParser.isYouTubeUrl(userInput)) {
    handleSharedUrl(userInput)
} else {
    // Treat as a search query
    coroutineScope.launch {
        val results = YouTube.search(userInput).getOrNull()
        // display results
    }
}

Building a WatchEndpoint from a URL

val url = "https://youtu.be/dQw4w9WgXcQ"

val endpoint = YouTubeUrlParser.createWatchEndpoint(url)
    ?: error("Not a video URL: $url")

coroutineScope.launch {
    YouTube.player(
        videoId = endpoint.videoId!!,
        playlistId = endpoint.playlistId
    )
}

Extracting a Bare Video ID

val videoId = YouTubeUrlParser.extractVideoId("https://www.youtube.com/shorts/abc123def45")
// "abc123def45"

YouTube Object

Data Models

Utilities

YouTubeUrlParser: Parse YouTube and YouTube Music URLs

`object YouTubeUrlParser`

`ParsedUrl` — Sealed Class

`ParsedUrl.Video`

`ParsedUrl.Artist`

`YouTubeUrlParser.parse(url: String): ParsedUrl?`

`YouTubeUrlParser.isYouTubeUrl(text: String): Boolean`

`YouTubeUrlParser.extractVideoId(url: String): String?`

`YouTubeUrlParser.createWatchEndpoint(url: String): WatchEndpoint?`

Usage Examples

Handling a Shared URL

Detecting YouTube URLs in User Input

Building a WatchEndpoint from a URL

Extracting a Bare Video ID

Build docs developers (and LLMs) love

YouTube Object

Data Models

Utilities

Documentation Index

​object YouTubeUrlParser

​ParsedUrl — Sealed Class

​ParsedUrl.Video

​ParsedUrl.Artist

​YouTubeUrlParser.parse(url: String): ParsedUrl?

​YouTubeUrlParser.isYouTubeUrl(text: String): Boolean

​YouTubeUrlParser.extractVideoId(url: String): String?

​YouTubeUrlParser.createWatchEndpoint(url: String): WatchEndpoint?

​Usage Examples

​Handling a Shared URL

​Detecting YouTube URLs in User Input

​Building a WatchEndpoint from a URL

​Extracting a Bare Video ID

Build docs developers (and LLMs) love

`object YouTubeUrlParser`

`ParsedUrl` — Sealed Class

`ParsedUrl.Video`

`ParsedUrl.Artist`

`YouTubeUrlParser.parse(url: String): ParsedUrl?`

`YouTubeUrlParser.isYouTubeUrl(text: String): Boolean`

`YouTubeUrlParser.extractVideoId(url: String): String?`

`YouTubeUrlParser.createWatchEndpoint(url: String): WatchEndpoint?`

Usage Examples

Handling a Shared URL

Detecting YouTube URLs in User Input

Building a WatchEndpoint from a URL

Extracting a Bare Video ID