Yt - a Ruby client for the YouTube API
Yt helps you write apps that need to interact with YouTube.
The full documentation is available at rubydoc.info.
After registering your app, you can run commands like:
channel = Yt::Channel.new id: 'UCxO1tY8h1AhOz0T4ENwmpow'
channel.title #=> "Fullscreen"
channel.description #=> "The first media company for the connected generation."
channel.public? #=> true
channel.view_count #=> 421619
channel.comment_count #=> 773
channel.video_count #=> 13
channel.subscriber_count #=> 136925
channel.subscriber_count_visible? #=> true
channel.videos.count #=> 13
video = Yt::Video.new id: 'MESycYJytkU'
video.title #=> "Fullscreen Creator Platform"
video.public? #=> true
video.view_count #=> 55843
video.comment_count #=> 308
video.like_count #=> 556
video.dislike_count #=> 78
video.favorite_count #=> 0
video.duration #=> 86
video.hd? #=> true
video.stereoscopic? #=> false
video. #=> true
video.licensed? #=> false
video.annotations.count #=> 1
The full documentation is available at rubydoc.info.
Available resources
Yt::Account
Use Yt::Account to:
- authenticate as a YouTube account
- read attributes of the account
- access the YouTube channel of the account
# An account can be initialized with access token, refresh token or an authorization code
account = Yt::Account.new access_token: 'ya29.1.ABCDEFGHIJ'
account.email #=> .. your e-mail address..
account.channel #=> #<Yt::Channel @id=...>
All the above methods require authentication (see below).
Yt::ContentOwner
Use Yt::ContentOwner to:
- authenticate as a YouTube content owner
- list the channels partnered with a YouTube content owner
# A content owner is an account, therefore can be initialized with access token, refresh token or an authorization code
content_owner = Yt::ContentOwner.new owner_name: 'CMSname', access_token: 'ya29.1.ABCDEFGHIJ'
content_owner.partnered_channels.count #=> 12
content_owner.partnered_channels.first #=> #<Yt::Channel @id=...>
All the above methods require authentication (see below).
Yt::Channel
Use Yt::Channel to:
- read attributes of a channel
- access the videos of a channel
- access the playlists of a channel
- subscribe to and unsubscribe from a channel
- create and delete playlists from a channel
- retrieve the estimated daily earnings of a channel
channel = Yt::Channel.new id: 'UCxO1tY8h1AhOz0T4ENwmpow'
channel.title #=> "Fullscreen"
channel.description.has_link_to_playlist? #=> false
channel.public? #=> true
channel.videos.count #=> 12
channel.videos.first #=> #<Yt::Video @id=...>
channel.playlists.count #=> 2
channel.playlists.first #=> #<Yt::Playlist @id=...>
The methods above do not require authentication.
account = Yt::Account.new access_token: 'ya29.1.ABCDEFGHIJ'
channel = Yt::Channel.new id: 'UCxO1tY8h1AhOz0T4ENwmpow', auth: account
channel.subscribed? #=> false
channel.subscribe #=> true
channel.create_playlist title: 'New playlist' #=> true
channel.delete_playlists title: 'New playlist' #=> [true]
The methods above require to be authenticated as a YouTube account (see below).
content_owner = Yt::ContentOwner.new owner_name: 'CMSname', access_token: 'ya29.1.ABCDEFGHIJ'
channel = Yt::Channel.new id: 'UCxO1tY8h1AhOz0T4ENwmpow', auth: content_owner
channel.earnings_on 5.days.ago #=> 12.23
channel.earnings since: 3.days.ago, until: 2.days.ago #=> {Wed, 28 May 2014 => 1.34, Thu, 29 May 2014 => 0.47}
channel.views_on 5.days.ago #=> 44
channel.views since: 3.days.ago, until: 2.days.ago #=> {Wed, 28 May 2014 => 12, Thu, 29 May 2014 => 3}
The methods above require to be authenticated as the channel’s content owner (see below).
Yt::Video
Use Yt::Video to:
- read attributes of a video
- access the annotations of a video
- like and dislike a video
video = Yt::Video.new id: 'MESycYJytkU'
video.title #=> "Fullscreen Creator Platform"
video.duration #=> 63
video.description.has_link_to_subscribe? #=> false
video.public? #=> true
video.annotations.count #=> 1
video.annotations.first #=> #<Yt::Annotation @id=...>
The methods above do not require authentication.
account = Yt::Account.new access_token: 'ya29.1.ABCDEFGHIJ'
video = Yt::Video.new id: 'MESycYJytkU', auth: account
video.liked? #=> false
video.like #=> true
The methods above require to be authenticated as a YouTube account (see below).
Yt::Playlist
Use Yt::Playlist to:
- read attributes of a playlist
- access the items of a playlist
- add one or multiple videos to a playlist
- delete items from a playlist
playlist = Yt::Playlist.new id: 'PLSWYkYzOrPMRCK6j0UgryI8E0NHhoVdRc'
playlist.title #=> "Fullscreen Features"
playlist.public? #=> true
playlist.playlist_items.count #=> 1
playlist.playlist_items.first #=> #<Yt::PlaylistItem @id=...>
playlist.playlist_items.first.position #=> 0
playlist.playlist_items.first.video.title #=> "Fullscreen Creator Platform"
The methods above do not require authentication.
playlist.add_video 'MESycYJytkU'
playlist.add_videos ['MESycYJytkU', 'MESycYJytkU']
playlist.delete_playlist_items title: 'Fullscreen Creator Platform' #=> [true]
The methods above require to be authenticated as the playlist’s owner (see below).
Yt::Annotation
Use Yt::Annotation to:
- read attributes of an annotation
video = Yt::Video.new id: 'MESycYJytkU'
annotation = video.annotations.first
annotation.below? 70 #=> false
annotation.has_link_to_subscribe? #=> false
annotation.has_link_to_playlist? #=> true
Annotations do not require authentication.
Configuring your app
In order to use Yt you must register your app in the Google Developers Console. Depending on the nature of your app, you should pick one of the following strategies.
Apps that do not require user interactions
If you are building a read-only app that fetches public data from YouTube, then generate a Public API access key in the Google Console. Next, add the following snippet of code to the initializer of your app:
Yt.configure do |config|
config.api_key = '123456789012345678901234567890'
end
replacing the value above with your own key for server application.
Remember: this kind of app is not allowed to perform any destructive operation, so you won’t be able to like a video, subscribe to a channel or delete a playlist from a specific account. You will only be able to retrieve read-only data.
Web apps that require user interactions
If you are building a web app that manages YouTube accounts, you need the owner of each account to authorize your app. There are three scenarios:
Scenario 1. If you already have the account’s access token, then you are ready to go. Just pass that access token to the account initializer, such as:
account = Yt::Account.new access_token: 'ya29.1.ABCDEFGHIJ'
account.email #=> (retrieves the account’s e-mail address)
account.playlists.first.add_video 'MESycYJytkU' #=> (adds a video to an account’s playlist)
Scenario 2. If you don’t have the account’s access token, but you have the refresh token, then it’s almost as easy. Open the Google Developers Console, find the client ID and client secret of the web application that you used to obtain the refresh token, then add the following snippet of code to the initializer of your app:
Yt.configure do |config|
config.client_id = '1234567890.apps.googleusercontent.com'
config.client_secret = '1234567890'
end
replacing the values above with the client ID and secret for web application. Then you can manage a YouTube account by passing the refresh token to the account initializer, such as:
account = Yt::Account.new refresh_token: '1/1234567890'
account.email #=> (retrieves the account’s e-mail address)
account.playlists.first.add_video 'MESycYJytkU' #=> (adds a video to an account’s playlist)
Scenario 3. If you don’t have any account’s token, then you can get one by having the user authorize your app through the Google OAuth page. First, build the the Google OAuth page URL with the following code:
Yt::Account.new(scopes: scopes, redirect_uri: redirect_uri).authentication_url
where scopes
is the list of scopes you want the user to authorize, and
redirect_uri
is the page of your web app the user should come back after
authorizing (remember, this must be added to the Google Console as well).
Sample scopes are: youtube
, youtube.readonly
userinfo.email
.
After authorizing your app, the user will be redirected to redirect_uri
with an extra code
parameter that looks something like 4/Ja60jJ7_Kw0
.
Just pass the code to the following method to authenticate and initialize the account:
account = Yt::Account.new authorization_code: '4/Ja60jJ7_Kw0'
account.email #=> (retrieves the account’s e-mail address)
account.playlists.first.add_video 'MESycYJytkU' #=> (adds a video to an account’s playlist)
Configuring with environment variables
As an alternative to the approach above, you can configure your app with variables. Setting the following environment variables:
export YT_CLIENT_SCENARIO="device_app"
export YT_CLIENT_ID="1234567890.apps.googleusercontent.com"
export YT_CLIENT_SECRET="1234567890"
export YT_API_KEY="123456789012345678901234567890"
is equivalent to configuring your app with the initializer:
Yt.configure do |config|
config.client_id = '1234567890.apps.googleusercontent.com'
config.client_secret = '1234567890'
config.api_key = '123456789012345678901234567890'
end
so use the approach that you prefer.
If a variable is set in both places, then Yt.configure
takes precedence.
How to install
To install on your system, run
gem install yt
To use inside a bundled Ruby project, add this line to the Gemfile:
gem 'yt', '~> 0.7.0'
Since the gem follows Semantic Versioning,
indicating the full version in your Gemfile (~> major.minor.patch)
guarantees that your project won’t occur in any error when you bundle update
and a new version of Yt is released.
Why you should use Yt…
… and not youtube_it? Because youtube_it does not support Google API V3 and the previous version has already been deprecated by Google and will soon be dropped.
… and not Google Api Client? Because Google Api Client is poorly coded, poorly documented and adds many dependencies, bloating the size of your project.
… and not your own code? Because Yt is fully tested, well documented, has few dependencies and helps you forget about the burden of dealing with Google API!
How to test
Yt comes with two different sets of tests:
- tests in
spec/models
andspec/collections
do not hit the YouTube API - tests in
spec/associations
hit the YouTube API and require authentication
To run all the tests, type:
rspec
The reason why some tests actually hit the YouTube API is because they are meant to really integrate Yt with YouTube. YouTube API is not exactly the most reliable API out there, so we need to make sure that the responses match the documentation.
You don’t have to run all the tests every time you change code. Travis CI is already set up to do this for when whenever you push a branch or create a pull request for this project.
Testing models and collections
To only run tests against models and collections (which do not hit the API), type:
rspec spec/models spec/collections
Testing associations
To only run tests against associations (which hit the API), type:
rspec spec/associations
This test will fail at first. As documented by the error message, you will need an app registered in the Google Developers Console to proceed.
Browse to the Console, then create a new app that you will only use for testing.
Under the "APIs" tab of this app, enable 'Google+ API', 'Youtube Analytics API' and 'YouTube Data API v3'.
Under the "Credentials" tab of this app, create a new 'Key for server application' and a new 'Client ID' and 'Client Secret' for native application.
It’s important that you pick 'native application' instead of 'web application', otherwise running your tests will require you to open a browser and launch a local webserver… and you don’t need to do any of that.
Finally, copy the given values and set the following environment variables:
export YT_TEST_DEVICE_CLIENT_ID="1234567890.apps.googleusercontent.com"
export YT_TEST_DEVICE_CLIENT_SECRET="1234567890"
export YT_TEST_SERVER_API_KEY="123456789012345678901234567890"
[ TODO: Complete this section. Explain how get and store the refresh token, making sure all the required scopes are authorized: 'https://www.googleapis.com/auth/youtube https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile' ]
How to contribute
Before you submit a pull request, make sure all the tests are passing and the code is fully test-covered.
To release an updated version of the gem to Rubygems, run:
rake release
Remember to bump the version before running the command, and to document your changes in HISTORY.md and README.md if required.
The yt gem follows Semantic Versioning. Any new release that is fully backward-compatible should bump the patch version (0.0.x). Any new version that breaks compatibility should bump the minor version (0.x.0)
Don’t hesitate to send code comments, issues or pull requests through GitHub! All feedback is appreciated. A googol of thanks! :)