Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
WebService::GData::YouUser(Contributed Perl DocumWebService::GData::YouTube(3)

NAME
       WebService::GData::YouTube - Access YouTube contents(read/write)	with
       API v2.

SYNOPSIS
	   use WebService::GData::YouTube;

	   #create an object that only has read	access
	   my $yt = new	WebService::GData::YouTube();

	   #get	a feed response	from YouTube;
	   my $videos  = $yt->get_top_rated_videos;
	   #more specific:
	   my $videos  = $yt->get_top_rated_videos('JP','Comedy');

	   foreach my $video (@$videos)	{
	       say $video->video_id;
	       say $video->title;
	       say $video->content;
	   }

	   #connect to a YouTube account
	   my $auth = new WebService::GData::ClientLogin(
	       email   =>'...'
	       password=>'...',
	       key     =>'...'
	   );

	   #give write access
	   my $yt = new	WebService::GData::YouTube($auth);

	   #returns all	the videos from	the logged in user
	   #including private ones.
	   my $videos  = $yt->get_user_videos();

	   #update the videos by adding	the common keywords if they are	public
	   #delete a certain video by checking its id.
	   foreach my $video (@$videos)	{

	       if($video->video_id eq $myid) {

		   $video->delete();

	       } else {

		   if($video->is_listing_allowed){

		       $video->keywords('music,live,guitar,'.$video->keywords);
		       $video->save();
		   }
	       }
	   }

DESCRIPTION
       !DEVELOPER RELEASE! API may change, program may break or	be under
       optimized.

       !DEVELOPER RELEASE! API may change, program may break or	be under
       optimized.

       !DEVELOPER RELEASE! API may change, program may break or	be under
       optimized.

       !WARNING! Documentation in progress.

       inherits	from WebService::GData

       This package is a point of entry	giving access to general YouTube
       feeds.  Passing an optional authorization object
       (WebService::GData::ClientLogin)	will allow you to access private
       contents.  It also offers some helper methods to	shorten	up the code.
       Most of the methods will	return one of the following object:

       WebService::GData::YouTube::Feed::Video
	   This	object handles the manipulation	of the video data such as
	   inserting/editing the metadata, uploading a video,etc.

       WebService::GData::YouTube::Feed::Comment
	   This	object handles the insertion of	comments on a video or in
	   reply to an other comment.

       WebService::GData::YouTube::Feed::Playlist
	   This	object inherits	from WebService::GData::YouTube::Feed::Video.
	   It contains a list of all the videos	within this particular
	   playlist.  The only difference with
	   WebService::GData::YouTube::Feed::Video is that it offers the
	   position tag	that specifies the position of the video within	the
	   playlist.

       WebService::GData::YouTube::Feed::PlaylistLink
	   This	object represents all the playlists metadata of	a user.	 It is
	   not possible	to get the metadata of one playlist. You need to query
	   them	all and	search for the one you're interested in.

       WebService::GData::YouTube::StagingServer
	   use this package at the very	top of your program to switch all the
	   read/writes urls to the staging server

	   See also:

	   o   WebService::GData::YouTube::Doc::BrowserBasedUpload - overview
	       of the browser based upload mechanism

	   o   WebService::GData::YouTube::Doc::GeneralOverview	- in progress
	       but should allow	you to learn the library easily

	   o   <http://szabgab.com/blog/2011/06/fetching-data-from-youtube-using-perl.html>
	       - a short video on the library by Gabor Szabo.

   CONSTRUCTOR
       new

	   Create a WebService::GData::YouTube instance.

	   Parameters

	   "auth:Object" (optional)  - Accept an optional authorization
	   object.
	       Only WebService::GData::ClientLogin is available	for now	but
	       OAuth should come anytime soon.	Passing	an auth	object allows
	       you to access private contents and insert/edit/delete data.

	   Returns

	   "WebService::GData::YouTube"	instance

	   Example:

	       use WebService::GData::ClientLogin;
	       use WebService::GData::YouTube;

	       #create an object that only has read access
	       my $yt =	new WebService::GData::YouTube();

	       #connect	to a YouTube account
	       my $auth	= new WebService::GData::ClientLogin(
		   email=>'...'
		   password=>'...',
		   key	      =>'...'
	       );

	       #give write access with a $auth object that you created
	       my $yt =	new WebService::GData::YouTube($auth);

   GENERAL METHODS
       query

	   Set/get a query object that handles the creation of the query
	   string sent to the service.	The query object will build the	query
	   string required to access the data.	All queries contain some
	   default parameters like the alt,v,strict parameters.	 You can add
	   other parameters in order to	do a search.

	   Parameters

	   "none" - getter context
	   "query:Object" - setter context accept a query string builder
	   instance. Default to	WebService::GData::YouTube::Query

	   Returns

	   "query:Object" in both setter/getter	context	the query object.
	   Default to WebService::GData::YouTube::Query

	   Example:

		   use WebService::GData::YouTube;

		   my $yt = new	WebService::GData::YouTube();

		   $yt->query()->q("ski")->limit(10,0);

		   #or set your	own query object
		   $yt->query($myquery);

		   my $videos =	$yt->search_video();

       base_uri

	   Get the base	uri used to query the data.

	   Parameters

	   "none"

	   Returns

	   "url:Scalar"	the root uri

       base_query

	   Get the base	query string used to get the data.

	   Parameters

	   "none"

	   Returns

	   "url:Scalar"	- default to ?alt=json&prettyprint=false&strict=true

       connection

	   Get the connection handler (WebService::GData::Base by default).
	   Mostly usefull to set connector settings.

	   Parameters

	   "none"

	   Returns

	   "object:Object" the connector instance,by default
	   WebService::GData::Base.

	   Example:

	       use WebService::GData::YouTube;

	       my $yt	= new WebService::GData::YouTube();
		  $yt->connection->timeout(100)->env_proxy;

   STANDARD FEED METHODS
       YouTube offers some feeds regarding videos like the most	discussed
       videos or the most viewed videos.  All the standard feed	methods	are
       implemented:

       methods

       get_top_rated_videos

       get_top_favorites_videos

       get_most_viewed_videos

       get_most_shared_videos

       get_most_popular_videos

       get_most_recent_videos

       get_most_discussed_videos

       get_most_responded_videos

       get_recently_featured_videos

       get_on_the_web_videos

       See
       http://code.google.com/intl/en/apis/youtube/2.0/developers_guide_protocol_video_feeds.html#Standard_feeds

	   All the above standard feed methods accept the following optional
	   parameters:

	   Parameters

	   "region_zone:Scalar"	- a country code - ie:JP,US.
	   "category:Scalar" - a video category	- ie:Comedy,Sports.
	   "time:Scalar" - a time  - ie:today,this_week,this_month,all_time

	   Returns

	   WebService::GData::Youtube::Feed::Video objects

	   Throws

	   WebService::GData::Error

	   Example:

	       use WebService::GData::YouTube;

	       my $yt	= new WebService::GData::YouTube();
	       my $videos = $yt->get_top_rated_videos();
	       my $videos = $yt->get_top_rated_videos('JP');#top rated videos in Japan
	       my $videos = $yt->get_top_rated_videos('JP','Comedy');#top rated	videos in Japanese Comedy
	       my $videos = $yt->get_top_rated_videos('JP','Comedy','today');#top rated	videos of the day in Japanese Comedy

	   See also:

	   Explanation of the different	standard feeds:

	   <http://code.google.com/intl/en/apis/youtube/2.0/reference.html#Standard_feeds>

   VIDEO FEED METHODS
       These methods allow you to access videos.  You do not need to be	logged
       in to use these methods.

       get_video_by_id

	   Get a video by its id.

	   Parameters

	   "video_id:Scalar" - the unique id of	the video- ie:Displayed	in the
	   url when watching a video. Looks like:Xzek3skD

	   Returns

	   WebService::GData::YouTube::Feed::Video

	   Throws

	   WebService::GData::Error

	   Example:

	       use WebService::GData::YouTube;

	       my $yt	= new WebService::GData::YouTube();

	       my $video = $yt->get_video_by_id('Xzek3skD');

       search_video

	   Send	a request to search for	videos.	 You create the	query by
	   calling $yt->query and by setting the available parameters.

	   Parameters

	   "query:Object" (optional) - a query builder instance

	   Returns

	   WebService::GData::YouTube::Feed::Video

	   Throws

	   WebService::GData::Error

	   Example:

	       use WebService::GData::YouTube;

	       my $yt	= new WebService::GData::YouTube();

		  $yt->query->q("ski")->limit(10,0);

	       my $videos = $yt->search_video();

	       #or

	       my $yt	  = new	WebService::GData::YouTube();
	       my $query  = $yt->query;
		  $query -> q("ski")->limit(10,0);
	       my $videos = $yt->search_video();

	       #or set a new query object
	       #it could be a sub class	that has predefined value

	       my $query  = new	WebService::GData::YouTube::Query();

		  $query -> q("ski")->limit(10,0);

	       my $videos = $yt->search_video($query);#this is a helper	the same as doing: $yt->query($query); $yt->search_video();

	   See also:

	   A list of all the query parameters and related methods you can use
	   with	the default query object:

	   WebService::GData::YouTube::Query

       get_related_for_video_id

	   Get the related videos for a	video.	These videos are returned by
	   following YouTube's own algorithm.

	   Parameters

	   "video_id:Scalar" - the unique identifier of	the video.

	   Returns

	   WebService::GData::YouTube::Feed::Video objects

	   Throws

	   WebService::GData::Error

	   Example:

	       my $yt	= new WebService::GData::YouTube();

	       my $videos = $yt->get_related_for_video_id('Xz2eFFexA');

       get_comments_for_video_id

	   Get the comments of a video.

	   Parameters

	   "video_id:Scalar" - the unique identifier of	the video.

	   Returns

	   WebService::GData::Collection instances of
	   WebService::GData::YouTube::Feed::Comment

	   Throws

	   WebService::GData::Error

	   Example:

	       use WebService::GData::YouTube;
	       my $yt	= new WebService::GData::YouTube();

	       my $comments = $yt->get_comments_for_video_id('Xz2eFFexA');

	       foreach my $comment (@$comments){
		   say $comment->content;
	       }

   USER	VIDEO FEED METHODS
       All these methods allow you to access the videos	of the programmaticly
       logged in user.	Being logged in	allow you to access private contents
       or contents that	have been uploaded but is not public yet.  The
       responses will also have	a read/write access so you will	be able	to
       edit the	videos.

       It does not mean	that you need to be logged in to use these methods.
       By setting the name of the user (channel	name),you will only get	a read
       access to the public data.

       get_user_video_by_id

	   Get a video for the logged in user or for the user name you
	   specified.  It queries the uploads feed which can be	more up	to
	   date	than the feed used with	"get_video_by_id()".

	   Parameters

	   "video_id:Scalar" - the id of the video
	   "user_name:Scalar" (optional) - the name of the user	(channel name)

	   Returns

	   WebService::GData::YouTube::Feed::Video objects

	   Throws

	   WebService::GData::Error

	   Example:

	       my $auth	= new WebService::GData::ClientLogin(email=>...);

	       my $yt	= new WebService::GData::YouTube($auth);

	       my $videos = $yt->get_user_video_by_id('Xz2eFFexA');

	       #if not logged in.
	       my $videos = $yt->get_user_video_by_id('Xz2eFFexA','live');#you must specify the	user if	not logged in!

       get_user_videos

	   Get the videos for the logged in user or for	the user name you
	   specified.

	   Parameters

	   "user_name:Scalar" (optional) - the user name/channel name

	   Returns

	   WebService::GData::YouTube::Feed::Video objects

	   Throws

	   WebService::GData::Error

	   Example:

	       my $auth	= new WebService::GData::ClientLogin(email=>...);

	       my $yt	= new WebService::GData::YouTube($auth);

	       my $videos = $yt->get_user_videos();

	       #if not logged in, pass the user	name as	the first parameter
	       my $videos = $yt->get_user_videos('live');

       get_user_favorite_videos

	   Get the videos that user specificly set a favorites (meaning	that
	   you may not have write access to the	content	even if	you are	logged
	   in!).

	   Parameters

	   "user_name:Scalar" (optional) - the user name/channel name

	   Returns

	   WebService::GData::YouTube::Feed::Video objects

	   Throws

	   WebService::GData::Error

	   Example:

	       my $auth	= new WebService::GData::ClientLogin(email=>...);

	       my $yt	= new WebService::GData::YouTube($auth);

	       my $videos = $yt->get_user_favorite_videos();

	       #if not logged in, pass the user	name as	the first parameter
	       my $videos = $yt->get_user_favorite_videos('live');

       add_favorite_video

	   Parameters

	   "video_id:Scalar" the video id you want to add as a favorite

	   Returns

	   void

	   Throws

	   WebService::GData::Error

	   Example:

	       my $auth	= new WebService::GData::ClientLogin(email=>...);

	       my $yt	= new WebService::GData::YouTube($auth);

		  $yt->add_favorite_video('video_id');

       get_recommended_videos

	   Get the videos that a user may be interested	in (defined by the
	   YouTube algorithm).

	   You must be logged in to use	this feature.

	   Parameters

	       none

	   Returns

	   WebService::GData::YouTube::Feed::Video objects

	   Throws

	   WebService::GData::Error

	   Example:

	       my $auth	= new WebService::GData::ClientLogin(email=>...);

	       my $yt	= new WebService::GData::YouTube($auth);

	       my $videos = $yt->get_recommended_videos();

   RATING METHODS
	   These methods allows	you to rate,like or dislike, a video.  They
	   are helper methods that instantiate a video instance	for you.

	   You must be logged in to use	these methods.

       like_video

       dislike_video

       Parameters

       "video_id:Scalar" the video id to rate

       Returns

       void

       Throws

       WebService::GData::Error

       Example:

	   my $auth = new WebService::GData::ClientLogin(email=>...);

	   my $yt   = new WebService::GData::YouTube($auth);

	      $yt->like_video('video_id');
	      $yt->dislike_video('video_id');

	  #in the background it	simply does:

	  my $vid = $yt->video;
	     $vid->video_id('video_id');
	     $vid->rate('like');

   VIDEO RESPONSE METHODS
	   These methods allow you to add a video as a response	to an other
	   video.  You can also	erase a	video response.

	   They	are helper methods that	instantiate a video instance for you.
	   You must be logged in to use	these methods.

       add_video_response

       Parameters

       "video_id:Scalar" the video id you want to response to
       "video_response_id:Scalar" the video id of the response

       Returns

       void

       Throws

       WebService::GData::Error

       Example:

	   my $auth = new WebService::GData::ClientLogin(email=>...);

	   my $yt   = new WebService::GData::YouTube($auth);

	      $yt->add_video_response('video_id','video_response_id');

       delete_video_response

       Parameters

       "video_id:Scalar" the video id that was responsed to
       "video_response_id:Scalar" the video id of the response

       Returns

       void

       Throws

       WebService::GData::Error

       Example:

	   my $auth = new WebService::GData::ClientLogin(email=>...);

	   my $yt   = new WebService::GData::YouTube($auth);

	      $yt->delete_video_response('video_id','video_response_id');

   FACTORY METHODS
	   These methods instantiate YouTube::Feed::* packages.	It just	saves
	   some	typing.

       video

       Return a	WebService::GData::YouTube::Feed::Video	instance

       comment

       Return a	WebService::GData::YouTube::Feed::Comment instance

       playlists

       Return a	WebService::GData::YouTube::Feed::PlaylistLink instance

       complaint

       Return a	WebService::GData::YouTube::Feed::Complaint instance

       contact

       Return a	WebService::GData::YouTube::Feed::Friend instance

       message

       Return a	WebService::GData::YouTube::Feed::VideoMessage instance

       Example:

	   use constant	KEY=>'...';

	   my $auth;
	   eval	{
	       $auth = new WebService::GData::ClientLogin(
		  email=>'...@gmail.com',
		  password=>'...',
		  key=>KEY
	      );
	   };

	   my $yt = new	WebService::GData::YouTube($auth);

	   #instantiate	a comment
	   my $comment = $yt->comment;

	      $comment->content('thank you all for watching!');
	      $comment->video_id('2lDekeCDD-J1');#attach the comment to	a video
	      $comment->save;

	   #instantiate	a video
	   my $video = $yt->video;

	      $video->title('Live at Shibuya tonight');
	      $video->description('Live	performance by 6 local bands.');
	      $video->keywords('music','live','shibuya','tokyo');
	      $video->category('Music');
	   #etc

   USER	PROFILE	RELATED	METHODS
       get_user_profile

	   Get the user	profile	info for the logged in user or the user	set as
	   a parameter.

	   Parameters

	   "user_name:Scalar" (optional) - the user name/channel name

	   Returns

	   WebService::GData::YouTube::Feed::UserProfile instance

	   Throws

	   WebService::GData::Error

	   Example:

	       use WebService::GData::ClientLogin;
	       use WebService::GData::YouTube;

	       my $auth	= new WebService::GData::ClientLogin(email=>...);

	       my $yt	= new WebService::GData::YouTube($auth);

	       my $profile = $yt->get_user_profile;

	       #or if you did not pass a $auth object:
	       my $profile = $yt->get_user_profile('profile_name_here');

       get_user_contacts

	   Get the user	contact	info for the logged in user or the user	set as
	   a parameter.	 A maximum of 100 contacts can be retrieved.

	   Parameters

	   "user_name:Scalar" (optional) - the user name/channel name

	   Returns

	   WebService::GData::Collection instance containing
	   WebService::GData::YouTube::Feed::Friend instances

	   Throws

	   WebService::GData::Error

	   Example:

	       use WebService::GData::ClientLogin;
	       use WebService::GData::YouTube;

	       my $auth	= new WebService::GData::ClientLogin(email=>...);

	       my $yt	= new WebService::GData::YouTube($auth);

	       my $contacts = $yt->get_user_contacts;

	       #or if you did not pass a $auth object:
	       my $contacts = $yt->get_user_contacts('profile_name_here');

       get_user_inbox

	   Get the user	inbox for the logged in	user.

	   Parameters

	   "none"

	   Returns

	   WebService::GData::Collection instance containing
	   WebService::GData::YouTube::Feed::VideoMessage instances

	   Throws

	   WebService::GData::Error

	   Example:

	       use WebService::GData::ClientLogin;
	       use WebService::GData::YouTube;

	       my $auth	= new WebService::GData::ClientLogin(email=>...);

	       my $yt	= new WebService::GData::YouTube($auth);

	       my $messages = $yt->get_user_inbox;

	       foreach my $message (@$messages){
		   say $message->subject;
		   say $message->content;
		   say $message->from->name;
		   say $message->sent;
	       }

   USER	PLAYLIST METHODS
	   !WARNING! Playlits related methods does not work perfectly yet!!

	   These methods allow you to access the videos	in a playlist or a
	   list	of playlists created by	a user.	 If you	are logged in, you
	   will	be able	to modify the data.  If	you are	not logged in,you will
	   only	have a read access and you must	set the	user name.

       get_user_playlist_by_id

	   Retrieve the	videos in a playlist by	passing	the playlist id.

	   Parameters

	   "playlist_id:Scalar"	- the id of the	playlist, looks	like
	   'CFESE01KESEQE'

	   Returns

	   WebService::GData::YouTube::Feed::Playlist
	       A WebService::GData::YouTube::Feed::Playlist contains the same
	       information as a	WebService::GData::YouTube::Feed::Video
	       instance

	       but adds	the position information of the	video within the
	       playlist.

	   Throws

	   WebService::GData::Error

	   Example:

	       my $auth	= new WebService::GData::ClientLogin(email=>...);#not compulsory

	       my $yt	= new WebService::GData::YouTube($auth);

	       my $videos_in_playlist =	$yt->get_user_playlist_by_id('CFESE01KESEQE');

	       #a feed returns by default up to	25 videos.
	       #you can	loop over the entire playlist (if you have more	than 25	videos)
	       #if your	playlist contains more than 50 videos, you can set the query limit to be 50
	       #it will	result in less calls to	the server.

	       while(my	$videos	= $yt->get_user_playlist_by_id('CFESE01KESEQE')){

		   foreach my $video (@$videos)	{
			   say $video->title;
		   }
	       }

       get_user_playlists

	   Get the playlists metadata for the logged in	user or	the user set
	   as a	parameter.

	   Parameters

	   "user_name:Scalar" (optional) - the user name/channel name

	   Returns

	   WebService::GData::YouTube::Feed::PlaylistLink objects
	       If you are logged in, you can access private playlists.

	       WebService::GData::YouTube::Feed::PlaylistLink is a list	of
	       playlists.  If you want to modify one playlist metadata,	you
	       must get	them all, loop until you find the one you want and
	       then edit.

	   Throws

	   WebService::GData::Error

	   Example:

	       use WebService::GData::Base;

	       my $auth	= new WebService::GData::ClientLogin(email=>...);

	       my $yt	= new WebService::GData::YouTube($auth);

	       my $playlists = $yt->get_user_playlists;

	       #or if you did not pass a $auth object:
	       my $playlists = $yt->get_user_playlists('live');

	       #a feed returns by default up to	25 entries/playlists.
	       #you can	loop over the channel playlists	(if you	have more than 25 playlists)
	       #if your	channels contains more than 50 playlists, you can set the query	limit to be 50
	       #it will	result in less calls to	the server.

	       #this is	a working example
	       #list all the programming related tutorials from	thenewboston channel:
	       my $yt =	new WebService::GData::YouTube();
		  $yt->query->max_results(50);

	       my $playlist_counter=1;
	       while(my	$playlists = $yt->get_user_playlists("thenewboston")) {

		   foreach my $playlist	(@$playlists) {
		       say($playlist_counter.':'.$playlist->title);

		       my $video_counter=1;
		       while(my	$videos	= $yt->get_user_playlist_by_id($playlist->playlist_id))	{
			   foreach my $vid (@$videos){
			   say(" ".$video_counter.':'.$vid->title);
			   $video_counter++;
			   }
		       }
		   }
		   $playlist_counter++;
	       }

   HANDLING ERRORS
       Google data APIs	relies on querying remote urls on particular services.
       Some of these services limits the number	of request with	quotas and may
       return an error code in such a case.  All queries that fail will	throw
       (die) a WebService::GData::Error	object.	 You should enclose all	code
       that requires connecting	to a service within eval blocks	in order to
       handle it.

       Example:

	   use WebService::GData::Base;

	   my ($auth,$videos);

	   eval	{
	       $auth = new WebService::GData::ClientLogin(email=>...);
	   };

	   my $yt   = new WebService::GData::YouTube($auth);

	   #the	server is dead or the url is not available anymore or you've reach your	quota of the day.
	   #boom the application dies and your program fails...

	   my $videos =	$yt->get_user_videos;

	   #with error handling...

	   #enclose your code in a eval	block...
	   eval	{
	       $videos = $yt->get_user_videos;
	   };

	   #if something went wrong, you will get a WebService::GData::Error object back:

	   if(my $error	= $@){

	       #do whatever you	think is necessary to recover (or not)
	       #print/log: $error->content,$error->code
	   }

   TODO
       Many things are left to be implemented!

       The YouTube API is very thorough	and it will take some time but by
       priority:

       o   OAuth authorization system

       o   Channel search

       o   Playlist search

       o   know	the status of a	video

       o   Partial Upload

       o   Partial feed	read/write

       Certainly missing many other stuffs...

DEPENDENCIES
       JSON
       LWP

BUGS AND LIMITATIONS
       If you do me the	favor to _use_ this module and find a bug, please
       email me	i will try to do my best to fix	it (patches welcome)!

AUTHOR
       shiriru <shirirulestheworld[arobas]gmail.com>

LICENSE	AND COPYRIGHT
       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 598:
	   You forgot a	'=back'	before '=head3'

	   You forgot a	'=back'	before '=head3'

       Around line 1190:
	   You forgot a	'=back'	before '=head3'

       Around line 1234:
	   =back without =over

       Around line 1246:
	   You forgot a	'=back'	before '=head3'

       Around line 1322:
	   =back without =over

       Around line 1331:
	   You forgot a	'=back'	before '=head3'

       Around line 1386:
	   =back without =over

perl v5.32.0			  2011-11-13	 WebService::GData::YouTube(3)

NAME | SYNOPSIS | DESCRIPTION | DEPENDENCIES | BUGS AND LIMITATIONS | AUTHOR | LICENSE AND COPYRIGHT | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=WebService::GData::YouTube&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help