Yt

https://nullscreen.github.io/yt/accounts.html
Admin
Yt is a reliable Ruby client for the YouTube API, designed to simplify interaction with YouTube...
Tokens:14,119
Snippets:93
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Expected Output for Yt Info Command

Source: https://nullscreen.github.io/yt/accounts.html/index

Shows the typical console output after successfully running the `yt info` command. This output confirms the Yt gem's version and demonstrates its ability to retrieve information, indicating a successful setup.

```Shell
Yt version 0.32.5
YouTube on the tube!
```

--------------------------------

### Verify Yt Gem Installation

Source: https://nullscreen.github.io/yt/accounts.html/index

Executes the `yt info` command in the terminal to verify the successful installation of the Yt gem. This command displays the installed Yt version and fetches a sample title from a YouTube video, confirming basic functionality.

```Shell
yt info
```

--------------------------------

### Install Yt Gem Globally

Source: https://nullscreen.github.io/yt/accounts.html/index

Installs the Yt gem globally on the system using the RubyGems package manager. This command is executed in the terminal and makes the `yt` executable available system-wide.

```Shell
gem install yt
```

--------------------------------

### Update Yt Gem Globally

Source: https://nullscreen.github.io/yt/accounts.html/index

Updates the Yt gem to its latest version installed globally on the system. This command should be run in the terminal to ensure you have the most recent features and bug fixes.

```Shell
gem update yt
```

--------------------------------

### Manage Yt::Channel Subscriptions

Source: https://nullscreen.github.io/yt/accounts.html/channels

Provides examples for subscribing to or unsubscribing from a channel, and checking the current subscription status. These operations require authentication as another channel's account.

```Ruby
channel.subscribe # => nil
channel.unsubscribe # => true
channel.subscribed? # => false
```

--------------------------------

### Yt::Video Analytics by Country

Source: https://nullscreen.github.io/yt/accounts.html/videos

Examples of `Yt::Video` analytics methods aggregated by country, showing how to retrieve metrics like views, comments, and estimated minutes watched broken down by geographical region.

```Ruby
video.views by: :country # => {"US" => 12, "IT" => 9, …}
```

```Ruby
video.comments by: :country # => {"US" => 7, "IT" => 5, …}
```

```Ruby
video.likes by: :country # => {"US" => 32, "IT" => 8, …}
```

```Ruby
video.dislikes by: :country # => {"US" => 87, "IT" => 6, …}
```

```Ruby
video.shares by: :country # => {"US" => 44, "IT" => 3, …}
```

```Ruby
video.subscribers_gained by: :country # => {"US" => 32, …}
```

```Ruby
video.subscribers_lost by: :country # => {"US" => 1, …}
```

```Ruby
video.favorites_added by: :country # => {"US" => 181, …}
```

```Ruby
video.favorites_removed by: :country # => {"US" => 0, …}
```

```Ruby
video.videos_added_to_playlists by: :country # => {"US" => 181, …}
```

```Ruby
video.videos_removed_from_playlists by: :country # => {"US" => 0, …}
```

```Ruby
video.average_view_duration by: :country # => {"US" => 456, …}
```

```Ruby
video.average_view_percentage by: :country # => {"US" => 38.85, …}
```

```Ruby
video.annotation_clicks by: :country # => {"US" => 329, …}
```

```Ruby
video.annotation_click_through_rate by: :country # => {"US" => 0.3, …}
```

```Ruby
video.annotation_close_rate by: :country # => {"US" => 0.1, …}
```

```Ruby
video.estimated_minutes_watched by: :country # => {"US" => 124, …}
```

--------------------------------

### Access Yt::Annotation Content and Link Properties

Source: https://nullscreen.github.io/yt/accounts.html/annotations

Provides examples of methods to retrieve the text content of an annotation (`text`) and to check for the presence of various types of links (subscribe, video, playlist, same window) and invideo programming. These methods allow detailed inspection of annotation functionality.

```Ruby
annotation.text # => "Hello, world!"
annotation.has_link_to_subscribe? # => true
annotation.has_link_to_video? # => false
annotation.has_link_to_playlist? # => true
annotation.has_link_to_same_window? # => false
annotation.has_invideo_programming? # => true
```

--------------------------------

### Yt Video Analytics Metrics and Dimensions

Source: https://nullscreen.github.io/yt/accounts.html/videos

Comprehensive documentation for accessing various video analytics metrics through the `Yt.docsvideo` object. Each entry shows a method call with different dimensions or filters and an example of the expected return structure.

```APIDOC
→ Yt docsvideo.estimated_minutes_watched by: :device_type # => {mobile: 57, …}
→ Yt docsvideo.estimated_minutes_watched by: :traffic_source # => {search: 3, …}
→ Yt docsvideo.estimated_minutes_watched by: :search_term # => {"music" => 7, …}
→ Yt docsvideo.estimated_minutes_watched by: :referrer # => {"Facebook" => 7, …}

→ Yt docsvideo.viewer_percentage # => {female: {'18-24' => 4.12, '25-34' => …}, …}
→ Yt docsvideo.viewer_percentage by: :gender # => {female: 12.3, male: 87.7}
→ Yt docsvideo.viewer_percentage by: :age_group # => {'18-24' => 4.1, '25-34' => …}

→ Yt docsvideo.reports only: [:views, :shares] # => {views: {…}, shares: {…}}
```

--------------------------------

### Yt::Video Analytics by US State

Source: https://nullscreen.github.io/yt/accounts.html/videos

Examples of `Yt::Video` analytics methods aggregated by US state, specifically for metrics like views, average view duration, average view percentage, annotation clicks, and estimated minutes watched.

```Ruby
video.views by: :state # => {"TX" => 12, "ND" => 9, …}
```

```Ruby
video.average_view_duration by: :state # => {"TX" => 456, …}
```

```Ruby
video.average_view_percentage by: :state # => {"TX" => 38.85, …}
```

```Ruby
video.annotation_clicks by: :state # => {"TX" => 329, …}
```

```Ruby
video.annotation_click_through_rate by: :state # => {"TX" => 0.3, …}
```

```Ruby
video.annotation_close_rate by: :state # => {"TX" => 0.1, …}
```

```Ruby
video.estimated_minutes_watched by: :state # => {"TX" => 124, …}
```

--------------------------------

### Add Yt Gem to Ruby Gemfile

Source: https://nullscreen.github.io/yt/accounts.html/index

Adds the Yt gem to a Ruby project's Gemfile, specifying a compatible version range (~> 0.32.5) for dependency management. This ensures that the project uses a version of Yt that is at least 0.32.5 but less than 0.33.0.

```Ruby
gem 'yt', '~> 0.32.5'
```

--------------------------------

### Yt::Video Analytics by Playback Location and Other Dimensions

Source: https://nullscreen.github.io/yt/accounts.html/videos

Examples of `Yt::Video` analytics methods aggregated by various dimensions such as playback location (e.g., watch page, embedded), embedded player location, related video, device type, subscribed status, traffic source, search term, and referrer.

```Ruby
video.views by: :playback_location # => {watch: 467, embedded: 53, …}
```

```Ruby
video.views by: :embedded_player_location # => {"fullscreen.net" => 92, …}
```

```Ruby
video.views by: :related_video, includes: [:status] # => {#<Yt::Video> => …}
```

```Ruby
video.views by: :device_type # => {mobile: 457, tv: 954, …}
```

```Ruby
video.views by: :subscribed_status # => {subscribed: 57, unsubscribed: 54}
```

```Ruby
video.views by: :traffic_source # => {advertising: 53, channel: 7, …}
```

```Ruby
video.views by: :search_term # => {"fullscreen" => 7, "music" => 3, …}
```

```Ruby
video.views by: :referrer # => {"Google Search" => 7, "ytimg.com" => 3, …}
```

```Ruby
video.estimated_minutes_watched by: :playback_location # => {watch: 17, …}
```

```Ruby
video.estimated_minutes_watched by: :embedded_player_location # => {"t.co"…}
```

```Ruby
video.estimated_minutes_watched by: :related_video # => {#<Yt::Video>…}
```

--------------------------------

### Access Yt::Video Live Broadcast Details

Source: https://nullscreen.github.io/yt/accounts.html/videos

Get information about a Yt::Video's live broadcast status, including content type, scheduled/actual start/end times, and concurrent viewers. This is available with any authentication.

```Ruby
video.live_broadcast_content # => "live"
video.scheduled_start_time # => 2015-03-31 06:16:46 UTC
video.scheduled_end_time # => 2015-03-31 07:16:46 UTC
video.actual_start_time # => 2015-03-31 06:16:48 UTC
video.actual_end_time # => nil
video.concurrent_viewers # => 12
```

--------------------------------

### Retrieve Channel Analytics Metrics by Country

Source: https://nullscreen.github.io/yt/accounts.html/channels

Examples demonstrating how to fetch various channel analytics metrics broken down by country. This allows for geographical analysis of audience engagement and performance.

```APIDOC
→ Yt docschannel.views by: :country # => {"US" => 33, "MX" => 12, …}
→ Yt docschannel.comments by: :country # => {"US" => 17, "FR" => 12, …}
→ Yt docschannel.likes by: :country # => {"US" => 32, "SG" => 3, …}
→ Yt docschannel.dislikes by: :country # => {"US" => 87, "MT" =>…}
→ Yt docschannel.shares by: :country # => {"US" => 44, "GR" => 7, …}
→ Yt docschannel.subscribers_gained by: :country # => {"CO" => 32, …}
→ Yt docschannel.subscribers_lost by: :country # => {"BM" => 1, …}
→ Yt docschannel.favorites_added by: :country # => {"BG" => 181, …}
→ Yt docschannel.favorites_removed by: :country # => {"PA" => 0, …}
→ Yt docschannel.videos_added_to_playlists by: :country # => {"BG" => 181, …}
→ Yt docschannel.videos_removed_from_playlists by: :country # => {"PA" => 0, …}
→ Yt docschannel.average_view_duration by: :country # => {"AW" => 456, …}
→ Yt docschannel.average_view_percentage by: :country # => {"PK" => 38.85, …}
→ Yt docschannel.annotation_clicks by: :country # => {"GT" => 329, …}
→ Yt docschannel.annotation_click_through_rate by: :country # => {"US" => …}
→ Yt docschannel.annotation_close_rate by: :country # => {"ZW" => 0.1, …}
→ Yt docschannel.estimated_minutes_watched by: :country # => {"US" => 12, …}
```

--------------------------------

### Get Yt::Video Monetization Details

Source: https://nullscreen.github.io/yt/accounts.html/videos

Access monetization-related details for a Yt::Video, including ad formats, estimated revenue, ad impressions, and playback-based CPM. This requires authentication as the video's content owner.

```Ruby
video.ad_formats # => ["standard_instream", "trueview_instream"]
video.estimated_revenue # => {Fri, 14 Oct 2016 => 455.1, …}
video.ad_impressions # => {Fri, 14 Oct 2016 => 84734, …}
video.playback_based_cpm # => {Wed, 8 May 2014 => 1.24, Thu, 9 May 2014 => …}
```

--------------------------------

### Retrieve Total Playlist Analytics Metrics

Source: https://nullscreen.github.io/yt/accounts.html/playlists

Demonstrates how to fetch various total analytics metrics for a playlist, such as views, average view duration, playlist starts, average time in playlist, views per playlist start, and estimated minutes watched, without any specific breakdown.

```APIDOC
→ Yt docsplaylist.views # => {total: 223}
→ Yt docsplaylist.average_view_duration # => {total: 234}
→ Yt docsplaylist.playlist_starts # => {total: 44}
→ Yt docsplaylist.average_time_in_playlist # => {total: 1.23}
→ Yt docsplaylist.views_per_playlist_start # => {total: 4.53}
→ Yt docsplaylist.estimated_minutes_watched # => {total: 12}
```

--------------------------------

### Check Yt::Annotation Duration Properties

Source: https://nullscreen.github.io/yt/accounts.html/annotations

Shows how to use `starts_after?` and `starts_before?` methods to check an annotation's start time relative to a specified duration in seconds. This helps in understanding when an annotation appears or disappears during a video.

```Ruby
annotation.starts_after? 4 # => false
annotation.starts_before? 20 # => true
```

--------------------------------

### Update Yt Gem in Ruby Project

Source: https://nullscreen.github.io/yt/accounts.html/index

Updates all gems within a Ruby project, including Yt, based on the project's Gemfile.lock. This command is typically run from the project's root directory and ensures all dependencies are up-to-date according to the Gemfile.

```Shell
bundle update
```

--------------------------------

### Get Yt::Video Embed HTML

Source: https://nullscreen.github.io/yt/accounts.html/videos

Retrieve the HTML snippet required to embed a Yt::Video player. This is available with any authentication.

```Ruby
video.embed_html # => "<iframe type='text/html' src='https://www.youtube…>"
```

--------------------------------

### Retrieve Yt::Channel Monetization Data

Source: https://nullscreen.github.io/yt/accounts.html/channels

Provides examples for accessing monetization-related data such as estimated revenue, ad impressions, playback-based CPM, and monetized playbacks. This data is typically available only with authentication as the channel's content owner.

```Ruby
channel.estimated_revenue # => {Fri, 14 Oct 2016 => 455.6, …}
channel.ad_impressions # => {Fri, 14 Oct 2016 => 847, …}
channel.playback_based_cpm # => {Wed, 8 May 2014 => 0.34, Thu, 9 May 2014 …}
channel.monetized_playbacks # => {Wed, 8 May 2014 => 53345, …}
```

--------------------------------

### Retrieve Playlist Analytics Metrics by Country

Source: https://nullscreen.github.io/yt/accounts.html/playlists

Shows how to break down playlist analytics metrics like views, average view duration, playlist starts, average time in playlist, views per playlist start, and estimated minutes watched by country, returning a hash with country codes as keys.

```APIDOC
→ Yt docsplaylist.views by: :country # => {"US" => 18, "RU" => 9, …}
→ Yt docsplaylist.average_view_duration by: :country # => {"US" => 456, …}
→ Yt docsplaylist.playlist_starts by: :country # => {"US" => 7, …}
→ Yt docsplaylist.average_time_in_playlist by: :country # => {"US" => 32.0, …}
→ Yt docsplaylist.views_per_playlist_start by: :country # => {"US" => 87, …}
→ Yt docsplaylist.estimated_minutes_watched by: :country # => {"US" => 12, …}
```

--------------------------------

### Get Yt::Video Statistics

Source: https://nullscreen.github.io/yt/accounts.html/videos

Fetch various statistics for a Yt::Video, such as view count, like count, dislike count, favorite count, and comment count. This information is typically available with any authentication.

```Ruby
video.view_count # => 9
video.like_count # => 1
video.dislike_count # => 0
video.favorite_count # => 3
video.comment_count # => 1
```

--------------------------------

### Retrieve Channel Analytics Metrics by US State

Source: https://nullscreen.github.io/yt/accounts.html/channels

Examples demonstrating how to fetch specific channel analytics metrics broken down by US state. This provides granular geographical insights for audiences within the United States.

```APIDOC
→ Yt docschannel.views by: :state # => {"TX" => 42, "SD" => 33, …}
→ Yt docschannel.average_view_duration by: :state # => {"CA" => 456, …}
→ Yt docschannel.average_view_percentage by: :state # => {"IL" => 38.85, …}
→ Yt docschannel.annotation_clicks by: :state # => {"TX" => 329, …}
→ Yt docschannel.annotation_click_through_rate by: :state # => {"TX" => …}
→ Yt docschannel.annotation_close_rate by: :state # => {"TX" => 0.1, …}
→ Yt docschannel.estimated_minutes_watched by: :state # => {"TX" => 12, …}
```

--------------------------------

### Retrieve Channel Viewer Demographics

Source: https://nullscreen.github.io/yt/accounts.html/channels

Example demonstrating how to fetch viewer demographic data for a YouTube channel, specifically viewer percentage broken down by gender and age groups. This provides insights into the channel's audience composition.

```APIDOC
→ Yt docschannel.viewer_percentage # => {female: {'18-24' => 4.12, '25-34' => …}, …}
```

--------------------------------

### Get Yt::Video Content Details

Source: https://nullscreen.github.io/yt/accounts.html/videos

Retrieve detailed content information for a Yt::Video, including duration, length in formatted string, stereoscopic status, HD status, captioning, licensing, and age restriction. This is available with any authentication.

```Ruby
video.duration # => 321
video.length # => "05:21"
video.stereoscopic? # => false
video.hd? # => false
video.captioned? # => true
video.licensed? # => false
video.age_restricted? # => false
```

--------------------------------

### Retrieve Total Channel Analytics Metrics

Source: https://nullscreen.github.io/yt/accounts.html/channels

Examples demonstrating how to fetch various aggregate metrics for a YouTube channel, such as total views, comments, likes, shares, subscribers, and engagement rates. These metrics provide an overall summary of channel performance.

```APIDOC
→ Yt docschannel.views # => {total: 345}
→ Yt docschannel.comments # => {total: 900}
→ Yt docschannel.likes # => {total: 934}
→ Yt docschannel.dislikes # => {total: 445}
→ Yt docschannel.shares # => {total: 913}
→ Yt docschannel.subscribers_gained # => {total: 334}
→ Yt docschannel.subscribers_lost # => {total: 345}
→ Yt docschannel.videos_added_to_playlists # => {total: 334}
→ Yt docschannel.videos_removed_from_playlists # => {total: 987}
→ Yt docschannel.average_view_duration # => {total: 10}
→ Yt docschannel.average_view_percentage # => {total: 34.3}
→ Yt docschannel.annotation_clicks # => {total: 91}
→ Yt docschannel.annotation_click_through_rate # => {total: 2.98}
→ Yt docschannel.annotation_close_rate # => {total: 3.34}
→ Yt docschannel.estimated_minutes_watched # => {total: 12}
→ Yt docschannel.card_impressions # => {total: 3}
→ Yt docschannel.card_clicks # => {total: 3}
→ Yt docschannel.card_click_rate # => {total: 0.65}
→ Yt docschannel.card_teaser_impressions # => {total: 3}
→ Yt docschannel.card_teaser_clicks # => {total: 3}
→ Yt docschannel.card_teaser_click_rate # => {total: 0.65}
```

--------------------------------

### Accessing Yt::Playlist Snippet Properties

Source: https://nullscreen.github.io/yt/accounts.html/playlists

Examples of retrieving various snippet-related properties from a `Yt::Playlist` object. These properties include basic metadata like ID, title, description, publication date, thumbnail URL, associated channel details, and tags.

```Ruby
playlist.id # => "PLSWYkYzOrPMRUYaLE6C9"
playlist.title # => "Fullscreen Arcade"
playlist.description # => "Retro games!"
playlist.published_at # => 2013-08-14 19:14:21 UTC
playlist.thumbnail_url # => "https://i.ytimg.com/vi/7gyM4Ue9nGY/default.jpg"
playlist.channel_id # => "UCxO1tY8h1AhOz0T4ENwmpow"
playlist.channel_title # => "Fullscreen"
playlist.tags # => ["arcade", "games"]
```

--------------------------------

### Authenticate Yt with Client ID, Secret, and Refresh Token

Source: https://nullscreen.github.io/yt/accounts.html/playlists

Illustrates how to configure Yt with client credentials and an account's refresh token to perform actions on behalf of a YouTube account. This setup is necessary for methods that modify playlists, such as adding videos.

```Ruby
Yt.configuration.client_id = "<your ID>"
Yt.configuration.client_secret = "<your secret>"
account = Yt::Account.new refresh_token: "<token>"

playlist = Yt::Playlist.new id: 'PLSWYkYzOrPMRUYaLE6C9', auth: account
playlist.add_video "BPNYv0vd78A"
```

--------------------------------

### Checking Yt::Playlist Privacy Status

Source: https://nullscreen.github.io/yt/accounts.html/playlists

Demonstrates how to query the privacy status of a `Yt::Playlist` object. This includes methods to get the status string and boolean checks for public, unlisted, or private visibility.

```Ruby
playlist.privacy_status # => "public"
playlist.public? # => true
playlist.unlisted? # => false
playlist.private? # => false
```

--------------------------------

### Retrieve Channel Analytics Metrics by Specific Dimensions

Source: https://nullscreen.github.io/yt/accounts.html/channels

Examples demonstrating how to fetch channel views and estimated minutes watched broken down by various dimensions such as video, playlist, traffic source, playback location, device type, and search terms. This allows for detailed analysis of content and audience behavior.

```APIDOC
→ Yt docschannel.views by: :video # => {#<Yt::Video @id=…> => 9, …}
→ Yt docschannel.views by: :playlist, includes: [:status] # => {#<Yt::Playlist> => …}
→ Yt docschannel.views by: :traffic_source # => {advertising: 53, channel: 7, …}
→ Yt docschannel.views by: :playback_location # => {watch: 467, embedded: 53, …}
→ Yt docschannel.views by: :embedded_player_location # => {"fullscreen.net" => 9, …}
→ Yt docschannel.views by: :device_type # => {mobile: 457, tv: 954, …}
→ Yt docschannel.views by: :subscribed_status # => {subscribed: 57, unsubscribed: 54}
→ Yt docschannel.views by: :related_video # => {#<Yt::Video @id=…> => 7, …}
→ Yt docschannel.views by: :search_term # => {"fullscreen" => 7, "music" => 3, …}
→ Yt docschannel.views by: :referrer # => {"Google Search" => 7, "ytimg.com" => 3, …}

→ Yt docschannel.estimated_minutes_watched by: :video # => {#<Yt::Video> => 9, …}
→ Yt docschannel.estimated_minutes_watched by: :playlist # => {#<Yt::Playlist> => …}
→ Yt docschannel.estimated_minutes_watched by: :traffic_source # => {channel: 7, …}
→ Yt docschannel.estimated_minutes_watched by: :playback_location # => {watch: 1, …}
→ Yt docschannel.estimated_minutes_watched by: :embedded_player_location # => {…}
→ Yt docschannel.estimated_minutes_watched by: :device_type # => {tv: 954, …}
→ Yt docschannel.estimated_minutes_watched by: :related_video # => {#<Yt::Video> => …}
→ Yt docschannel.estimated_minutes_watched by: :search_term # => {"music" => 7, …}
→ Yt docschannel.estimated_minutes_watched by: :referrer # => {"Facebook" => 7, …}
```

--------------------------------

### Retrieve Views Metrics by Various Dimensions

Source: https://nullscreen.github.io/yt/accounts.html/playlists

Examples of breaking down playlist views by different dimensions such as individual video, related playlist, traffic source, playback location, device type, related video, search term, and referrer. This allows for granular analysis of view origins.

```APIDOC
→ Yt docsplaylist.views by: :video, includes: [:status] # => {#<Yt::Video> => 9, …}
→ Yt docsplaylist.views by: :playlist # => {#<Yt::Playlist @id=…> => 4, …}
→ Yt docsplaylist.views by: :traffic_source # => {channel: 7, …}
→ Yt docsplaylist.views by: :playback_location # => {watch: 467, embedded: 53, …}
→ Yt docsplaylist.views by: :device_type # => {mobile: 457, tv: 954, …}
→ Yt docsplaylist.views by: :related_video # => {#<Yt::Video @id=…> => 7, …}
→ Yt docsplaylist.views by: :search_term # => {"fullscreen" => 7, "music" => 3, …}
→ Yt docsplaylist.views by: :referrer # => {"Google Search" => 7, "ytimg.com" => 3, …}
```

--------------------------------

### Updating Yt::Playlist Properties and Items

Source: https://nullscreen.github.io/yt/accounts.html/playlists

Examples of methods to modify a `Yt::Playlist`, including updating its title and privacy status, adding single or multiple videos, and deleting specific playlist items. These operations require authentication as the playlist's owner.

```Ruby
playlist.update title: "Videos I like", privacy_status: "public" # => true
playlist.add_video "BPNYv0vd78A" # => #<Yt::PlaylistItem …>
playlist.add_videos %w{BPNYv0vd78A 2NW_AqhkYZZ} # => [#<Yt::PlaylistItem …>]
playlist.delete_playlist_items video_id: "BPNYv0vd78A" # => [true, false]
```

--------------------------------

### Retrieving Yt::Playlist Analytics Data

Source: https://nullscreen.github.io/yt/accounts.html/playlists

Examples of using analytics methods on a `Yt::Playlist` object to fetch view counts. Demonstrates options for specifying date ranges, requesting daily breakdowns, and filtering results by geographic location (country or state).

```Ruby
playlist.views # => {total: 949}

range = {since: 2.months.ago, until: 1.month.ago} # use a Date or String
playlist.views range # => {total: 219}
playlist.views range.merge(by: :day) # => {Wed, 8 May 2014 => 12, Thu, 9 May 2014 …}

playlist.views in: 'FR' # => {total: 45}
playlist.views in: {country: 'US'} # => {total: 113}
playlist.views in: {state: 'TX'} # => {total: 11}
```

--------------------------------

### Retrieve Estimated Minutes Watched by Various Dimensions

Source: https://nullscreen.github.io/yt/accounts.html/playlists

Examples of breaking down estimated minutes watched by different dimensions including individual video, related playlist, traffic source, playback location, device type, related video, search term, and referrer. This provides insights into watch time origins.

```APIDOC
→ Yt docsplaylist.estimated_minutes_watched by: :video # => {#<Yt::Video> => 9, …}
→ Yt docsplaylist.estimated_minutes_watched by: :playlist # => {#<Yt::Playlist> => …}
→ Yt docsplaylist.estimated_minutes_watched by: :traffic_source # => {channel: 7, …}
→ Yt docsplaylist.estimated_minutes_watched by: :playback_location # => {watch: …}
→ Yt docsplaylist.estimated_minutes_watched by: :device_type # => {tv: 954, …}
→ Yt docsplaylist.estimated_minutes_watched by: :related_video # => {#<Yt::Video>…}
→ Yt docsplaylist.estimated_minutes_watched by: :search_term # => {"music" => 7, …}
→ Yt docsplaylist.estimated_minutes_watched by: :referrer # => {"Facebook" => 7, …}
```

--------------------------------

### Initialize Yt::Account with Access or Refresh Token

Source: https://nullscreen.github.io/yt/accounts.html/accounts

Demonstrates how to create a new `Yt::Account` instance using either an access token or a refresh token. Both initialization methods result in a `Yt::Account` object identified by its unique ID.

```Ruby
account = Yt::Account.new access_token:  'ya29.ZAF6McAOf0OwU'
account = Yt::Account.new refresh_token: '1/ddxHq4ph-BdR954Xh'
# => All these methods return #<Yt::Account:0x... @id="11668677593">
```

--------------------------------

### Yt::Video Class API Reference

Source: https://nullscreen.github.io/yt/accounts.html/videos

Comprehensive API documentation for the `Yt::Video` class, detailing its initialization, properties, and methods, along with the required authentication contexts for various operations. It also lists other Yt classes that return `Yt::Video` objects.

```APIDOC
Class: Yt::Video
  Description: Represents a YouTube video.

  Initialization:
    Yt::Video.new(id: String)
      id: The YouTube video ID.
    Yt::Video.new(url: String)
      url: The YouTube video URL.
    Yt::Video.new(id: String, auth: Yt::Account | Yt::ContentOwner)
      id: The YouTube video ID.
      auth: An authenticated Yt::Account or Yt::ContentOwner object for actions requiring specific permissions.

  Methods (Public Data - requires Server API Key):
    video.description() -> String
      Description: Retrieves the video's description.
      Authentication: Yt.configuration.api_key

  Methods (Account Actions - requires Client ID/Secret + Refresh Token):
    video.like() -> Boolean
      Description: Likes the video on behalf of the authenticated account.
      Authentication: Yt::Account object passed via :auth parameter during initialization.

  Methods (Content Owner Actions - requires Client ID/Secret + Refresh Token):
    video.estimated_revenue(since: Date) -> Hash
      Description: Fetches estimated revenue data for the video.
      Parameters:
        since: The start date for revenue calculation (e.g., 3.days.ago).
      Authentication: Yt::ContentOwner object passed via :auth parameter during initialization.

  Returned by:
    Yt::Account#upload_video
    Yt::Account#videos (collection)
    Yt::Channel#videos (collection)
    Yt::Playlist#videos (collection)
```

--------------------------------

### Authenticate and Perform Account Actions (e.g., Upload Video)

Source: https://nullscreen.github.io/yt/accounts.html/accounts

Illustrates the process of configuring Yt with client credentials and then using an authenticated `Yt::Account` to perform actions on behalf of a YouTube account, such as uploading a video. This requires obtaining an access or refresh token for the target account.

```Ruby
Yt.configuration.client_id = "<your ID>"           ## replace with your client ID
Yt.configuration.client_secret = "<your secret>"   ## replace with your client secret
account = Yt::Account.new refresh_token: "<token>" ## use the account’s refresh token

account.upload_video "http://example.com/remote_video.mp4", title: 'My video'
# => #<Yt::Video …>
```

--------------------------------

### Initialize Yt::Video Object by ID

Source: https://nullscreen.github.io/yt/accounts.html/videos

Demonstrates the basic method to create a new `Yt::Video` instance using a YouTube video ID. This is the fundamental way to represent a YouTube video within the Yt Ruby client for subsequent operations.

```Ruby
video = Yt::Video.new id:  'BPNYv0vd78A'
# => #<Yt::Video:0x... @id="BPNYv0vd78A">
```

--------------------------------

### Initialize Yt::PlaylistItem in Ruby

Source: https://nullscreen.github.io/yt/accounts.html/playlist_items

Demonstrates how to create a `Yt::PlaylistItem` object using its ID or by retrieving the first item from a `Yt::Playlist` object. Both methods return a `Yt::PlaylistItem` instance, representing a specific entry in a YouTube playlist.

```Ruby
item = Yt::PlaylistItem.new id: 'PLjW_GNR5Ir0GWEP_ove'
item = Yt::Playlist.new(id: 'PLSWYkYzOrPMRUYaLE6C9').playlist_items.first
# => All these methods return #<Yt::PlaylistItem:0x... @id="PLjW_GNR5Ir0GWEP_ove">
```

--------------------------------

### Perform Actions on Behalf of a YouTube Account

Source: https://nullscreen.github.io/yt/accounts.html/videos

Shows how to authenticate with a YouTube account using a client ID/secret and a refresh token, then perform actions like liking a video on behalf of that account. This requires obtaining an access or refresh token through user interaction.

```Ruby
Yt.configuration.client_id = "<your ID>"           ## replace with your client ID
Yt.configuration.client_secret = "<your secret>"   ## replace with your client secret
account = Yt::Account.new refresh_token: "<token>" ## use the account’s refresh token

video = Yt::Video.new id: 'BPNYv0vd78A', auth: account
video.like
# => true (the video was liked on on behalf of the account)
```

--------------------------------

### Configure API Key and Fetch Public Video Data

Source: https://nullscreen.github.io/yt/accounts.html/videos

Illustrates how to configure the Yt client with a Server API key to retrieve public video data, such as the video's description. This type of interaction does not require user authentication and is suitable for accessing publicly available information.

```Ruby
Yt.configuration.api_key = "<your api key>" ## replace with your API key

video = Yt::Video.new id: 'BPNYv0vd78A'     ## use any public video ID
video.description
# => "A test video for the Yt gem"
```

--------------------------------

### Initialize Yt::Annotation from a Yt::Video

Source: https://nullscreen.github.io/yt/accounts.html/annotations

Demonstrates how to obtain an instance of `Yt::Annotation` by accessing the `annotations` collection of a `Yt::Video` object. This is the primary way to interact with video annotations.

```Ruby
video = Yt::Video.new id: 'BPNYv0vd78A'
video.annotations.first
# => #<Yt::Annotation:0x…>
```

--------------------------------

### Aggregate Video Analytics by Day or Month

Source: https://nullscreen.github.io/yt/accounts.html/videos

Illustrates how to obtain analytics values per day or month within a specified range using the `:by` option. This allows for granular data analysis rather than just a single total.

```Ruby
video.views by: :day # => {Wed, 8 May 2014 => 6, Thu, 9 May 2014 => 7, …}
```

```Ruby
video.views by: :month # => {Fri, 01 May 2015..Sun, 31 May 2015=>130192, …}
```

--------------------------------

### Initialize Yt::Playlist with ID

Source: https://nullscreen.github.io/yt/accounts.html/playlists

Demonstrates how to create a new `Yt::Playlist` object by providing its YouTube ID. This is the basic instantiation method for interacting with a specific playlist.

```Ruby
playlist = Yt::Playlist.new id:  'PLSWYkYzOrPMRUYaLE6C9'
```

--------------------------------

### Authenticate and Perform Content Owner Actions (e.g., Fetch Channel Owners)

Source: https://nullscreen.github.io/yt/accounts.html/accounts

Demonstrates how to authenticate as a YouTube content owner using `Yt::ContentOwner` and then use that authentication context to perform actions that require content owner privileges, such as retrieving channel owners associated with an account.

```Ruby
Yt.configuration.client_id = "<your ID>"           ## replace with your client ID
Yt.configuration.client_secret = "<your secret>"   ## replace with your client secret
owner = Yt::ContentOwner.new owner_name: "<name>", ## replace with owner’s credentials
                             refresh_token: "<token>"

account = Yt::Account.new id: owner.id, authentication: owner.authentication
account.channel_owners
# => #<Yt::Collections::ChannelOwners …>
```

--------------------------------

### Yt::Account API: Content Owner Methods

Source: https://nullscreen.github.io/yt/accounts.html/accounts

Documents methods on `Yt::Account` related to content owner information. These methods require content owner privileges.

```APIDOC
Yt::Account
  #owner_name: string - The name of the content owner.
  #content_owners: Yt::Collections::ContentOwners - A collection of content owners associated with the account.
```

--------------------------------

### Yt::Channel Class API Reference

Source: https://nullscreen.github.io/yt/accounts.html/channels

Comprehensive API documentation for the Yt::Channel class, detailing its initialization, properties, and methods, along with the authentication requirements for different operations.

```APIDOC
Yt::Channel
  Represents a YouTube channel.

  Initialization:
    Yt::Channel.new(id: String)
      id: The YouTube channel ID.
    Yt::Channel.new(auth: Yt::Account | Yt::ContentOwner, id: String)
      auth: An authenticated Yt::Account or Yt::ContentOwner object.
      id: The YouTube channel ID.

  Methods (Public Data - requires API Key):
    #title
      Returns the channel's title.
      Example usage: channel.title

  Methods (Account Actions - requires Yt::Account authentication):
    #subscribe
      Subscribes the authenticated account to the channel.
      Returns: Boolean (true on success).
      Example usage: channel.subscribe

  Methods (Content Owner Actions - requires Yt::ContentOwner authentication):
    #estimated_revenue(since: Date)
      since: The start date for revenue estimation.
      Returns: Hash of dates to revenue figures.
      Example usage: channel.estimated_revenue since: 3.days.ago

  Related Classes/Methods:
    Yt::Account#channel
      Returns a Yt::Channel object for the account's own channel.
    Yt::Account#subscribed_channels
      Returns a collection of Yt::Channel objects the account is subscribed to.
    Yt::Account
      Used for account-based authentication.
    Yt::ContentOwner
      Used for content owner-based authentication.
```

--------------------------------

### Yt::Account API: User Information Methods

Source: https://nullscreen.github.io/yt/accounts.html/accounts

Documents methods available on `Yt::Account` for retrieving various user profile details. These methods require authentication as a YouTube account.

```APIDOC
Yt::Account
  #id: string - The account's unique ID.
  #email: string - The account's email address.
  #has_verified_email?: boolean - Indicates if the account's email is verified.
  #name: string - The account's full name.
  #given_name: string - The account's given name.
  #family_name: string - The account's family name.
  #profile_url: string - The URL to the account's Google+ profile.
  #avatar_url: string - The URL to the account's avatar image.
  #gender: string - The account's gender.
  #locale: string - The account's locale (e.g., 'en').
  #hd: string - The hosted domain associated with the account (e.g., 'example.com').
```

--------------------------------

### Configure Yt for Account-Based Authentication in Ruby

Source: https://nullscreen.github.io/yt/accounts.html/playlist_items

Illustrates how to set up `Yt` with a Client ID/Secret and an account's refresh token for actions requiring user authorization, such as deleting a playlist item. This enables operations on behalf of a YouTube account and requires obtaining tokens from the user.

```Ruby
Yt.configuration.client_id = "<your ID>"           ## replace with your client ID
Yt.configuration.client_secret = "<your secret>"   ## replace with your client secret
account = Yt::Account.new refresh_token: "<token>" ## use the account’s refresh token

item = Yt::PlaylistItem.new id: 'PLjW_GNR5Ir0GWEP_ove', auth: account
item.delete
# => true
```

--------------------------------

### Fetch Content Owner Data (Estimated Revenue)

Source: https://nullscreen.github.io/yt/accounts.html/videos

Demonstrates how to authenticate as a YouTube content owner using a client ID/secret and a refresh token to access sensitive data, such as estimated video revenue. This requires specific content owner credentials and permissions.

```Ruby
Yt.configuration.client_id = "<your ID>"           ## replace with your client ID
Yt.configuration.client_secret = "<your secret>"   ## replace with your client secret
owner = Yt::ContentOwner.new owner_name: "<name>", ## replace with owner’s credentials
                             refresh_token: "<token>"

video = Yt::Video.new id: 'BPNYv0vd78A', auth: owner
video.estimated_revenue since: 3.days.ago
# => {Wed, 8 May 2014 => 12.3, Thu, 9 May 2014 => 3.7, Fri, 10 May 2014 => …}
```

--------------------------------

### Initialize Yt::Channel by ID

Source: https://nullscreen.github.io/yt/accounts.html/channels

Demonstrates how to create a new Yt::Channel object by providing a YouTube channel ID. This is the fundamental step to interact with a specific channel using the Yt client.

```Ruby
channel = Yt::Channel.new id:  'UCxO1tY8h1AhOz0T4ENwmpow'
# => #<Yt::Channel:0x... @id="UCxO1tY8h1AhOz0T4ENwmpow">
```

--------------------------------

### Yt::Annotation Class API Reference

Source: https://nullscreen.github.io/yt/accounts.html/annotations

Detailed API documentation for the `Yt::Annotation` class, listing all available methods for inspecting annotation properties such as location, duration, and content. All listed methods do not require any form of authentication.

```APIDOC
Yt::Annotation Class Methods:
  - above?(value: Integer) -> Boolean
    Description: Checks if the annotation is positioned above the given vertical pixel value.
    Example: annotation.above? 50 # => false

  - below?(value: Integer) -> Boolean
    Description: Checks if the annotation is positioned below the given vertical pixel value.
    Example: annotation.below? 30 # => true

  - starts_after?(time_in_seconds: Integer) -> Boolean
    Description: Checks if the annotation starts appearing after the specified time in seconds.
    Example: annotation.starts_after? 4 # => false

  - starts_before?(time_in_seconds: Integer) -> Boolean
    Description: Checks if the annotation starts appearing before the specified time in seconds.
    Example: annotation.starts_before? 20 # => true

  - text -> String
    Description: Returns the textual content of the annotation.
    Example: annotation.text # => "Hello, world!"

  - has_link_to_subscribe? -> Boolean
    Description: Checks if the annotation contains a link to subscribe to a channel.
    Example: annotation.has_link_to_subscribe? # => true

  - has_link_to_video? -> Boolean
    Description: Checks if the annotation contains a link to another video.
    Example: annotation.has_link_to_video? # => false

  - has_link_to_playlist? -> Boolean
    Description: Checks if the annotation contains a link to a playlist.
    Example: annotation.has_link_to_playlist? # => true

  - has_link_to_same_window? -> Boolean
    Description: Checks if the annotation's link opens in the same browser window.
    Example: annotation.has_link_to_same_window? # => false

  - has_invideo_programming? -> Boolean
    Description: Checks if the annotation includes invideo programming elements.
    Example: annotation.has_invideo_programming? # => true
```

--------------------------------

### Configure Yt for Public API Key Authentication in Ruby

Source: https://nullscreen.github.io/yt/accounts.html/playlist_items

Shows how to configure the `Yt` client with a Server API key for retrieving public data, such as a playlist item's position. This authentication is sufficient for read-only operations on public data and does not require user interaction.

```Ruby
Yt.configuration.api_key = "<your api key>"             ## replace with your API key

item = Yt::PlaylistItem.new id: 'PLjW_GNR5Ir0GWEP_ove'
item.position
# => 3
```

--------------------------------

### Yt::Video Analytics Methods Overview (Total)

Source: https://nullscreen.github.io/yt/accounts.html/videos

A comprehensive list of available analytics methods for `Yt::Video` objects, showing their default output (total lifetime value). To access these analytics, authentication as the video’s account or content owner is required.

```Ruby
video.views # => {total: 3453}
```

```Ruby
video.comments # => {total: 304}
```

```Ruby
video.likes # => {total: 459}
```

```Ruby
video.dislikes # => {total: 923}
```

```Ruby
video.shares # => {total: 223}
```

```Ruby
video.subscribers_gained # => {total: 232}
```

```Ruby
video.subscribers_lost # => {total: 904}
```

```Ruby
video.videos_added_to_playlists # => {total: 224}
```

```Ruby
video.videos_removed_from_playlists # => {total: 322}
```

```Ruby
video.average_view_duration # => {total: 23}
```

```Ruby
video.average_view_percentage # => {total: 2.45}
```

```Ruby
video.annotation_clicks # => {total: 723}
```

```Ruby
video.annotation_click_through_rate # => {total: 8.34}
```

```Ruby
video.annotation_close_rate # => {total: 0.34}
```

```Ruby
video.estimated_minutes_watched # => {total: 4}
```

```Ruby
video.card_impressions # => {total: 3}
```

```Ruby
video.card_clicks # => {total: 3}
```

```Ruby
video.card_click_rate # => {total: 0.65}
```

```Ruby
video.card_teaser_impressions # => {total: 3}
```

```Ruby
video.card_teaser_clicks # => {total: 3}
```

```Ruby
video.card_teaser_click_rate # => {total: 0.65}
```

--------------------------------

### Identify Yt::Video Rejection Reasons

Source: https://nullscreen.github.io/yt/accounts.html/videos

Check for specific reasons why a Yt::Video might have been rejected, such as copyright infringement, duplication, or terms of use violation. This is available with any authentication.

```Ruby
video.claimed? # => false
video.infringes_copyright? # => false
video.duplicate? # => false
video.too_long? # => false
video.violates_terms_of_use? # => false
video.inappropriate? # => false
video.infringes_trademark? # => false
video.belongs_to_closed_account? # => false
video.belongs_to_suspended_account? # => false
```

--------------------------------

### Access Yt::Channel Snippet Properties

Source: https://nullscreen.github.io/yt/accounts.html/channels

Demonstrates how to retrieve basic channel information such as ID, title, description, published date, and thumbnail URL using the `Yt::Channel` object. This information is typically available without special authentication.

```Ruby
channel.id # => "UCxO1tY8h1AhOz0T4ENwmpow"
channel.title # => "Fullscreen"
channel.description # => "The media company for the connected generation"
channel.published_at # => 2006-03-23 06:13:25 UTC
channel.thumbnail_url # => "https://yt3.ggpht.com/-KMnbKDBl60w/photo.jpg"
```

--------------------------------

### Access Yt::Video File Details

Source: https://nullscreen.github.io/yt/accounts.html/videos

Obtain file-specific details for a Yt::Video, such as file size, file type, and container format. This requires authentication as the video's account.

```Ruby
video.file_size # => 8000000
video.file_type # => "video"
video.container # => "mov"
```

--------------------------------

### Identify Yt::Video Failure Reasons

Source: https://nullscreen.github.io/yt/accounts.html/videos

Check for specific reasons why a Yt::Video upload might have failed, such as unsupported codec, failed conversion, or invalid file. This is available with any authentication.

```Ruby
video.uses_unsupported_codec? # => false
video.has_failed_conversion? # => false
video.empty? # => false
video.invalid? # => false
video.too_small? # => false
video.aborted? # => false
```

--------------------------------

### Initialize Yt CommentThread and Comment Objects

Source: https://nullscreen.github.io/yt/accounts.html/comments

Demonstrates how to create new instances of `Yt::CommentThread` and `Yt::Comment` using their respective IDs. These objects represent a YouTube comment thread and a single comment (top-level or reply), respectively.

```Ruby
comment_thread = Yt::CommentThread.new id: 'z13fsrejbwf3dziea22pd5trmyqbjteoa04'
comment = Yt::Comment.new id: 'z13fsrejbwf3dziea22pd5trmyqbjteoa04'
```
Tokens:
Raw