Types - YTMusicAPI PHP

Type System Overview

YTMusicAPI PHP uses docblock-typed objects to document the data returned from the YouTube Music API. These types are defined as PHP classes with documented properties using PHPDoc annotations. Most objects returned are actually stdclass objects retrieved directly from YouTube's data, but the docblock annotations allow your intellisense to provide you with the correct properties.

Core Types

These are the fundamental types used throughout the library.

SearchResult

Represents a single search result item. The type of content depends on the resultType property.

Properties

category string

Category of search result: "Top results", "Songs", "Videos", "Albums", "Artists", "Playlists", etc.

resultType string

Type of result: "album", "artist", "playlist", "song", "video", "station", "profile", "podcast", "episode"

title string

Title of the search result (not valid for artist results)

artists TrackArtist[]

Artists (valid for songs, videos, and albums)

browseId string

Browse ID for detailed information

videoId string

Video ID (for songs and videos)

duration string

Duration in MM:SS format

thumbnails Thumbnail[]

Thumbnail images

$results = $yt->search("Oasis Wonderwall");
foreach ($results as $result) {
    if ($result->resultType === "song") {
        echo "Song: " . $result->title . "\n";
        echo "Video ID: " . $result->videoId . "\n";
    }
}

Song

Complete song information including streaming data and metadata.

Properties

playabilityStatus PlayabilityStatus

Playability information and status

streamingData StreamingData

Streaming URLs and formats

videoDetails VideoDetails

Video metadata (title, author, duration, etc.)

microformat Microformat

Additional metadata and tags

$song = $yt->get_song("kJQP7kiw5Fk");
echo "Title: " . $song->videoDetails->title . "\n";
echo "Playable: " . ($song->playabilityStatus->status === "OK" ? "Yes" : "No") . "\n";

Track

Simplified track information used in playlists and library results.

Properties

title string

Track title

videoId string

Video ID

artists TrackArtist[]

Track artists

album Ref

Album reference

duration string

Duration in MM:SS format

inLibrary bool

Whether track is in your library

isExplicit bool

Whether track has explicit content

Search Types

Types specifically related to search functionality.

TrackArtist

Artist information in track contexts.

Properties

name string

Artist name

id string

Artist channel ID

foreach ($track->artists as $artist) {
    echo "Artist: " . $artist->name . " (ID: " . $artist->id . ")\n";
}

Content Types

Types for different kinds of content (albums, artists, playlists).

Playlist

Complete playlist information including tracks and metadata.

Properties

id string

Playlist ID

title string

Playlist title

description string

Playlist description

privacy string

Privacy status: "PUBLIC", "PRIVATE", or "UNLISTED"

trackCount int

Number of tracks in playlist

duration string

Total duration

author Ref

Playlist author

tracks Track[]

Array of tracks in the playlist

continuation string

Continuation token for loading more tracks

$playlist = $yt->get_playlist("PLfY7JYgRs-QJZP7zqsKPFMqKJ5qghLqm_");
echo "Playlist: " . $playlist->title . "\n";
echo "Tracks: " . $playlist->trackCount . "\n";
echo "Duration: " . $playlist->duration . "\n";

Artist

Complete artist information including songs, albums, and related content.

Properties

name string

Artist name

channelId string

Artist channel ID

description string

Artist description

subscribers string

Subscriber count

subscribed bool

Whether you're subscribed to this artist

songs SongList

Artist's popular songs

albums AlbumList

Artist's albums

singles SingleList

Artist's singles

Album

Album information including tracks and metadata.

Properties

title string

Album title

type string

Album type: "Album", "Single", "EP"

artist Ref

Primary artist

year string

Release year

trackCount int

Number of tracks

duration string

Total duration

tracks Track[]

Album tracks

Library Types

Types for user library content and account information.

Account

User account information. (PHP-specific type)

Properties

name string

Account name

channelId string

Account channel ID

is_premium bool

Whether account has YouTube Music Premium

thumbnails Thumbnail[]

Profile pictures

$account = $yt->get_account();
if ($account->is_premium) {
    echo "Premium user: " . $account->name . "\n";
}

SongInfo

Basic song information with music detection. (PHP-specific type)

Properties

music bool

Whether this is actual music (not just a video)

videoId string

Video ID

title string

Track title

author string

Track author

canEmbed bool

Whether track can be embedded

Media Types

Types for media content and streaming information.

Episode

Podcast episode information.

Properties

title string

Episode title

author Ref

Podcast/channel information

date string

Publication date

duration string

Episode duration

playlistId string

Episode playlist ID

description string

Episode description

$episode = $yt->get_episode("nDnLSYCOg7E");
echo "Episode: " . $episode->title . "\n";
echo "Podcast: " . $episode->author->name . "\n";

WatchList

Watch playlist for continuous playback.

Properties

tracks Track[]

List of tracks for playback

playlistId string

Watch playlist ID

lyrics string

Lyrics browse ID (if available)

related string

Common Properties

Properties and types that appear across multiple objects.

Thumbnail

Image thumbnail information.

Properties

url string

Thumbnail URL

width int

Image width in pixels

height int

Image height in pixels

foreach ($artist->thumbnails as $thumbnail) {
    echo "Thumbnail: " . $thumbnail->width . "x" . $thumbnail->height . "\n";
    echo "URL: " . $thumbnail->url . "\n";
}

Ref

Reference object containing ID and name for linked content.

Properties

name string

Display name

id string

ID for browsing (browseId or channelId)

// Used for artists, albums, authors, etc.
echo "Album: " . $track->album->name . "\n";
$album_details = $yt->get_album($track->album->id);

FeedbackTokens

Tokens for adding/removing items from library.

Properties

add string

Token for adding to library

remove string

Token for removing from library

Type Usage Patterns

<?php
// Most API methods return strongly-typed objects
$results = $yt->search("Radiohead");  // Returns SearchResult[]
$playlist = $yt->get_playlist("PLxyz");  // Returns Playlist
$artist = $yt->get_artist("UCxyz");  // Returns Artist

// Access properties with IDE autocomplete support
echo $playlist->title;  // string
echo $playlist->trackCount;  // int
echo $playlist->tracks[0]->title;  // string

// Check types at runtime if needed
if ($result->resultType === "song") {
    // $result has song-specific properties
    echo "Duration: " . $result->duration . "\n";
}

// Many objects contain references to related content
$track = $playlist->tracks[0];
if ($track->album) {
    $album_details = $yt->get_album($track->album->id);
}

IDE Support: All types include PHPDoc annotations for better IDE support and autocomplete functionality.

Optional Properties: Many properties may be null or undefined depending on the content type and availability. Always check for null values before accessing nested properties.

Complete Type List

The library includes these type definitions:

Type	Purpose	Used By
Account	User account information	get_account()
SearchResult	Search result item	search()
Song	Complete song data	get_song()
SongInfo	Basic song information	get_song_info()
Track	Track in playlist/library	Playlist tracks, library songs
WatchTrack	Track with playback information	get_track()
Playlist	Playlist information	get_playlist()
Artist	Artist information	get_artist()
Album	Album information	get_album()
Episode	Podcast episode	get_episode()
Podcast	Podcast information	get_podcast()
UploadTrack	Uploaded track	Upload methods
WatchList	Watch playlist	get_watch_playlist()
Thumbnail	Image information	All content types
Ref	Reference with ID and name	Artists, albums, authors