Class: Yt::Models::Playlist

Inherits:
Resource show all
Defined in:
lib/yt/models/playlist.rb

Overview

Provides methods to interact with YouTube playlists.

See Also:

Instance Attribute Summary collapse

Attributes inherited from Resource

#auth, #id

Instance Method Summary collapse

Methods inherited from Resource

#initialize, #kind, #privacy_status, #private?, #public?, #unlisted?, #username

Methods included from Associations::HasOne

#has_one

Methods included from Associations::HasMany

#has_many

Methods included from Associations::HasAuthentication

#has_authentication

Constructor Details

This class inherits a constructor from Yt::Models::Resource

Instance Attribute Details

#channel_id ⇒ String (readonly)

Returns the ID of the channel that the playlist belongs to.

Returns:

  • (String) —

    the ID of the channel that the playlist belongs to.



34
 
# File 'lib/yt/models/playlist.rb', line 34

delegate :channel_id, to: :snippet

#channel_title ⇒ String (readonly)

Returns the title of the channel that the playlist belongs to.

Returns:

  • (String) —

    the title of the channel that the playlist belongs to.



38
 
# File 'lib/yt/models/playlist.rb', line 38

delegate :channel_title, to: :snippet

#description ⇒ String (readonly)

Returns the playlist’s description.

Returns:

  • (String) —

    the playlist’s description.



17
 
# File 'lib/yt/models/playlist.rb', line 17

delegate :description, to: :snippet

#playlist_items ⇒ Yt::Collections::PlaylistItems (readonly)

Returns the playlist’s items.

Returns:



150
 
# File 'lib/yt/models/playlist.rb', line 150

has_many :playlist_items

#published_at ⇒ Time (readonly)

Returns the date and time that the playlist was created.

Returns:

  • (Time) —

    the date and time that the playlist was created.



30
 
# File 'lib/yt/models/playlist.rb', line 30

delegate :published_at, to: :snippet

#tags ⇒ Array<String> (readonly)

Returns the list of tags attached to the playlist.

Returns:

  • (Array<String>) —

    the list of tags attached to the playlist.



42
 
# File 'lib/yt/models/playlist.rb', line 42

delegate :tags, to: :snippet

#title ⇒ String (readonly)

Returns the playlist’s title.

Returns:

  • (String) —

    the playlist’s title.



13
 
# File 'lib/yt/models/playlist.rb', line 13

delegate :title, to: :snippet

Instance Method Details

#add_video(video_id, options = {}) ⇒ Yt::PlaylistItem

Adds a video to the playlist. Unlike #add_video!, does not raise an error if video can’t be added.

Parameters:

  • video_id (String) —

    the video to add to the playlist.

  • options (Hash) (defaults to: {}) —

    the options on how to add the video.

Options Hash (options):

  • :position (Integer) —

    where to add video in the playlist.

Returns:

Raises:



87
88
89
90
 
# File 'lib/yt/models/playlist.rb', line 87

def add_video(video_id, options = {})
  playlist_item_params = playlist_item_params(video_id, options)
  playlist_items.insert playlist_item_params, ignore_errors: true
end

#add_video!(video_id, options = {}) ⇒ Yt::PlaylistItem

Adds a video to the playlist. Unlike #add_video, raises an error if video can’t be added.

Parameters:

  • video_id (String) —

    the video ID to add to the playlist.

  • options (Hash) (defaults to: {}) —

    the options on how to add the video.

Options Hash (options):

  • :position (Integer) —

    where to add video in the playlist.

Returns:

Raises:



101
102
103
104
 
# File 'lib/yt/models/playlist.rb', line 101

def add_video!(video_id, options = {})
  playlist_item_params = playlist_item_params(video_id, options)
  playlist_items.insert playlist_item_params
end

#add_videos(video_ids = [], options = {}) ⇒ Array<Yt::PlaylistItem>

Adds multiple videos to the playlist. Unlike #add_videos!, does not raise an error if videos can’t be added.

Parameters:

  • video_ids (Array<String>) (defaults to: []) —

    the video IDs to add to the playlist.

  • options (Hash) (defaults to: {}) —

    the options on how to add the videos.

Options Hash (options):

  • :position (Integer) —

    where to add videos in the playlist.

Returns:

Raises:



114
115
116
 
# File 'lib/yt/models/playlist.rb', line 114

def add_videos(video_ids = [], options = {})
  video_ids.map{|video_id| add_video video_id, options}
end

#add_videos!(video_ids = [], options = {}) ⇒ Array<Yt::PlaylistItem>

Adds multiple videos to the playlist. Unlike #add_videos, raises an error if videos can’t be added.

Parameters:

  • video_ids (Array<String>) (defaults to: []) —

    the video IDs to add to the playlist.

  • options (Hash) (defaults to: {}) —

    the options on how to add the videos.

Options Hash (options):

  • :position (Integer) —

    where to add videos in the playlist.

Returns:

Raises:



126
127
128
 
# File 'lib/yt/models/playlist.rb', line 126

def add_videos!(video_ids = [], options = {})
  video_ids.map{|video_id| add_video! video_id, options}
end

#average_time_in_playlist(options = {}) ⇒ Hash<Date, Float>

Returns the average_time_in_playlist grouped by the given dimension.

Examples:

Get the average_time_in_playlist for each day of last week:

resource.average_time_in_playlist since: 2.weeks.ago, until: 1.week.ago, by: :day
# => {Wed, 8 May 2014 => 12.0, Thu, 9 May 2014 => 34.2, …}

Parameters:

  • options (Hash) (defaults to: {}) —

    the time-range and dimensions for the average_time_in_playlist.

Options Hash (options):

  • :by (Symbol) — default: :day —

    The dimension to collect average_time_in_playlist by. Accepted values are: :day.

  • :since (#to_date) —

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date) —

    The last day of the time-range. Also aliased as :to.

Returns:

  • (Hash<Date, Float>) —

    if grouped by day, the average_time_in_playlist for each day in the time-range.



170
 
# File 'lib/yt/models/playlist.rb', line 170

has_report :average_time_in_playlist

#average_view_duration(options = {}) ⇒ Hash<Date, Float>

Returns the average_view_duration grouped by the given dimension.

Examples:

Get the average_view_duration for each day of last week:

resource.average_view_duration since: 2.weeks.ago, until: 1.week.ago, by: :day
# => {Wed, 8 May 2014 => 12.0, Thu, 9 May 2014 => 34.2, …}

Parameters:

  • options (Hash) (defaults to: {}) —

    the time-range and dimensions for the average_view_duration.

Options Hash (options):

  • :by (Symbol) — default: :day —

    The dimension to collect average_view_duration by. Accepted values are: :day.

  • :since (#to_date) —

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date) —

    The last day of the time-range. Also aliased as :to.

Returns:

  • (Hash<Date, Float>) —

    if grouped by day, the average_view_duration for each day in the time-range.



164
 
# File 'lib/yt/models/playlist.rb', line 164

has_report :average_view_duration

#delete(options = {}) ⇒ Boolean

Deletes the playlist.

Returns:

  • (Boolean) —

    whether the playlist does not exist anymore.

Raises:



50
51
52
53
 
# File 'lib/yt/models/playlist.rb', line 50

def delete(options = {})
  do_delete {@id = nil}
  !exists?
end

#delete_playlist_items(attributes = {}) ⇒ Array<Boolean>

Deletes the playlist’s items matching all the given attributes.

Parameters:

  • attributes (Hash) (defaults to: {}) —

    the attributes to match the items by.

Options Hash (attributes):

  • :title (<String, Regexp>) —

    The item’s title. Pass a String for perfect match or a Regexp for advanced match.

  • :description (<String, Regexp>) —

    The item’s description. Pass a String (perfect match) or a Regexp (advanced).

  • :privacy_status (String) —

    The item’s privacy status.

  • :video_id (String) —

    The item’s video ID.

Returns:

  • (Array<Boolean>) —

    whether each playlist item matching the given attributes was deleted.

Raises:



142
143
144
 
# File 'lib/yt/models/playlist.rb', line 142

def delete_playlist_items(attributes = {})
  playlist_items.delete_all attributes
end

#estimated_minutes_watched(options = {}) ⇒ Hash<Yt::Video, Float>, ...

Returns the estimated_minutes_watched grouped by the given dimension.

Examples:

Get yesterday’s estimated_minutes_watched by video:

resource.estimated_minutes_watched from: 1.day.ago, to: 1.day.ago, by: :video
# => {#<Yt::Video @id=…> => 33.0, #<Yt::Video @id=…> => 12.0, …}

Get yesterday’s estimated_minutes_watched by playlist:

resource.estimated_minutes_watched from: 1.day.ago, to: 1.day.ago, by: :playlist
# => {#<Yt::Video @id=…> => 33.0, #<Yt::Video @id=…> => 12.0, …}

Get yesterday’s estimated_minutes_watched grouped by playback location:

resource.estimated_minutes_watched from: 1.day.ago, to: 1.day.ago, by: :playback_location
# => {embedded: 53.0, watch: 467.0, …}

Get yesterday’s estimated_minutes_watched by related video:

resource.estimated_minutes_watched from: 1.day.ago, to: 1.day.ago, by: :related_video
# => {#<Yt::Video @id=…> => 33.0, #<Yt::Video @id=…> => 12.0, …}

Get yesterday’s estimated_minutes_watched by device type:

resource.estimated_minutes_watched from: 1.day.ago, to: 1.day.ago, by: :device_type
# => {mobile: 133.0, tv: 412.0, …}

Get yesterday’s estimated_minutes_watched by traffic source:

resource.estimated_minutes_watched from: 1.day.ago, to: 1.day.ago, by: :traffic_source
# => {advertising: 543.0, playlist: 92.0, …}

Get the estimated_minutes_watched for each day of last week:

resource.estimated_minutes_watched since: 2.weeks.ago, until: 1.week.ago, by: :day
# => {Wed, 8 May 2014 => 12.0, Thu, 9 May 2014 => 34.2, …}

Parameters:

  • options (Hash) (defaults to: {}) —

    the time-range and dimensions for the estimated_minutes_watched.

Options Hash (options):

  • :by (Symbol) — default: :day —

    The dimension to collect estimated_minutes_watched by. Accepted values are: :day, :traffic_source, :playback_location, :related_video, :video, :playlist.

  • :since (#to_date) —

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date) —

    The last day of the time-range. Also aliased as :to.

Returns:

  • (Hash<Yt::Video, Float>) —

    if grouped by video, the estimated_minutes_watched for each video.

  • (Hash<Yt::Video, Float>) —

    if grouped by playlist, the estimated_minutes_watched for each playlist.

  • (Hash<Symbol, Float>) —

    if grouped by playback location, the estimated_minutes_watched for each traffic playback location.

  • (Hash<Yt::Video, Float>) —

    if grouped by related video, the estimated_minutes_watched for each related video.

  • (Hash<Yt::Video, Float>) —

    if grouped by device type, the estimated_minutes_watched for each device type.

  • (Hash<Yt::Video, Float>) —

    if grouped by traffic source, the estimated_minutes_watched for each traffic source.

  • (Hash<Date, Float>) —

    if grouped by day, the estimated_minutes_watched for each day in the time-range.



158
 
# File 'lib/yt/models/playlist.rb', line 158

has_report :estimated_minutes_watched

#playlist_starts(options = {}) ⇒ Hash<Date, Float>

Returns the playlist_starts grouped by the given dimension.

Examples:

Get the playlist_starts for each day of last week:

resource.playlist_starts since: 2.weeks.ago, until: 1.week.ago, by: :day
# => {Wed, 8 May 2014 => 12.0, Thu, 9 May 2014 => 34.2, …}

Parameters:

  • options (Hash) (defaults to: {}) —

    the time-range and dimensions for the playlist_starts.

Options Hash (options):

  • :by (Symbol) — default: :day —

    The dimension to collect playlist_starts by. Accepted values are: :day.

  • :since (#to_date) —

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date) —

    The last day of the time-range. Also aliased as :to.

Returns:

  • (Hash<Date, Float>) —

    if grouped by day, the playlist_starts for each day in the time-range.



167
 
# File 'lib/yt/models/playlist.rb', line 167

has_report :playlist_starts

#thumbnail_url(size = :default) ⇒ String?

Returns the URL of the playlist’s thumbnail.

Parameters:

  • size (Symbol, String) (defaults to: :default) —

    The size of the playlist’s thumbnail.

Returns:

  • (String) —

    if size is default, the URL of a 120x90px image.

  • (String) —

    if size is medium, the URL of a 320x180px image.

  • (String) —

    if size is high, the URL of a 480x360px image.

  • (nil) —

    if the size is not default, medium or high.



26
 
# File 'lib/yt/models/playlist.rb', line 26

delegate :thumbnail_url, to: :snippet

#update(attributes = {}) ⇒ Boolean

Updates the attributes of a playlist.

Examples:

Update title and description of a playlist.

playlist.update title: 'New title', description: 'New description'

Update tags and status of a playlist.

playlist.update tags: ['new', 'tags'], privacy_status: 'public'

Parameters:

  • attributes (Hash) (defaults to: {}) —

    the attributes to update.

Options Hash (attributes):

  • :title (String) —

    The new playlist’s title. Cannot have more than 100 characters. Can include the characters < and >, which are replaced to ‹ › in order to be accepted by YouTube.

  • :description (String) —

    The new playlist’s description. Cannot have more than 5000 bytes. Can include the characters < and >, which are replaced to ‹ › in order to be accepted by YouTube.

  • :tags (Array<String>) —

    The new playlist’s tags. Cannot have more than 500 characters. Can include the characters < and >, which are replaced to ‹ › in order to be accepted by YouTube.

  • :privacy_status (String) —

    The new playlist’s privacy status. Must be one of: private, unscheduled, public.

Returns:

  • (Boolean) —

    whether the playlist was successfully updated.

Raises:



75
76
77
 
# File 'lib/yt/models/playlist.rb', line 75

def update(attributes = {})
  super
end

#viewer_percentage(options = {}) ⇒ Hash<Symbol, Float>, ...

Returns the viewer_percentage grouped by the given dimension.

Examples:

Get yesterday’s viewer percentage by gender:

resource.viewer_percentage from: 1.day.ago, to: 1.day.ago, by: :gender
# => {female: 53.0, male: 47.0}

Get yesterday’s viewer_percentage grouped by age group:

resource.viewer_percentage from: 1.day.ago, to: 1.day.ago, by: :age_group
# => {"18-24" => 4.54, "35-24" => 12.31, "45-34" => 8.92, …}

Get yesterday’s viewer_percentage by gender and age group:

resource.viewer_percentage from: 1.day.ago, to: 1.day.ago
# => {female: {"18-24" => 12.12, "25-34" => 16.16, …}, male:…}

Parameters:

  • options (Hash) (defaults to: {}) —

    the time-range and dimensions for the viewer_percentage.

Options Hash (options):

  • :by (Symbol) — default: :gender_age_group —

    The dimension to show viewer percentage by. Accepted values are: :gender, :age_group, :gender_age_group.

  • :since (#to_date) —

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date) —

    The last day of the time-range. Also aliased as :to.

Returns:

  • (Hash<Symbol, Float>) —

    if grouped by gender, the viewer percentage by gender.

  • (Hash<String, Float>) —

    if grouped by age group, the viewer percentage by age group.

  • (Hash<Symbol, [Hash<String, Float>]>) —

    if grouped by gender and age group, the viewer percentage by gender/age group.



161
 
# File 'lib/yt/models/playlist.rb', line 161

has_report :viewer_percentage

#views(options = {}) ⇒ Hash<Yt::Video, Float>, ...

Returns the views grouped by the given dimension.

Examples:

Get yesterday’s views by video:

resource.views from: 1.day.ago, to: 1.day.ago, by: :video
# => {#<Yt::Video @id=…> => 33.0, #<Yt::Video @id=…> => 12.0, …}

Get yesterday’s views by playlist:

resource.views from: 1.day.ago, to: 1.day.ago, by: :playlist
# => {#<Yt::Video @id=…> => 33.0, #<Yt::Video @id=…> => 12.0, …}

Get yesterday’s views grouped by playback location:

resource.views from: 1.day.ago, to: 1.day.ago, by: :playback_location
# => {embedded: 53.0, watch: 467.0, …}

Get yesterday’s views by related video:

resource.views from: 1.day.ago, to: 1.day.ago, by: :related_video
# => {#<Yt::Video @id=…> => 33.0, #<Yt::Video @id=…> => 12.0, …}

Get yesterday’s views by device type:

resource.views from: 1.day.ago, to: 1.day.ago, by: :device_type
# => {mobile: 133.0, tv: 412.0, …}

Get yesterday’s views by traffic source:

resource.views from: 1.day.ago, to: 1.day.ago, by: :traffic_source
# => {advertising: 543.0, playlist: 92.0, …}

Get the views for each day of last week:

resource.views since: 2.weeks.ago, until: 1.week.ago, by: :day
# => {Wed, 8 May 2014 => 12.0, Thu, 9 May 2014 => 34.2, …}

Parameters:

  • options (Hash) (defaults to: {}) —

    the time-range and dimensions for the views.

Options Hash (options):

  • :by (Symbol) — default: :day —

    The dimension to collect views by. Accepted values are: :day, :traffic_source, :playback_location, :related_video, :video, :playlist.

  • :since (#to_date) —

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date) —

    The last day of the time-range. Also aliased as :to.

Returns:

  • (Hash<Yt::Video, Float>) —

    if grouped by video, the views for each video.

  • (Hash<Yt::Video, Float>) —

    if grouped by playlist, the views for each playlist.

  • (Hash<Symbol, Float>) —

    if grouped by playback location, the views for each traffic playback location.

  • (Hash<Yt::Video, Float>) —

    if grouped by related video, the views for each related video.

  • (Hash<Yt::Video, Float>) —

    if grouped by device type, the views for each device type.

  • (Hash<Yt::Video, Float>) —

    if grouped by traffic source, the views for each traffic source.

  • (Hash<Date, Float>) —

    if grouped by day, the views for each day in the time-range.



155
 
# File 'lib/yt/models/playlist.rb', line 155

has_report :views

#views_per_playlist_start(options = {}) ⇒ Hash<Date, Float>

Returns the views_per_playlist_start grouped by the given dimension.

Examples:

Get the views_per_playlist_start for each day of last week:

resource.views_per_playlist_start since: 2.weeks.ago, until: 1.week.ago, by: :day
# => {Wed, 8 May 2014 => 12.0, Thu, 9 May 2014 => 34.2, …}

Parameters:

  • options (Hash) (defaults to: {}) —

    the time-range and dimensions for the views_per_playlist_start.

Options Hash (options):

  • :by (Symbol) — default: :day —

    The dimension to collect views_per_playlist_start by. Accepted values are: :day.

  • :since (#to_date) —

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date) —

    The last day of the time-range. Also aliased as :to.

Returns:

  • (Hash<Date, Float>) —

    if grouped by day, the views_per_playlist_start for each day in the time-range.



173
 
# File 'lib/yt/models/playlist.rb', line 173

has_report :views_per_playlist_start