WebService::Viddler - An encapsulation of the Viddler video platform in Perl
Version 0.10
use WebService::Viddler;
my $videos = new WebService::Viddler( apiKey => $apiKey, username => $username, password => $passwd, );
print "API Version: " .$videos->api_getInfo(). "\n";
$video->videos_upload( $title, $tags, $description, $make_public, $file, $bitrate );
$video->videos_getDetails( $video_id, $add_embed_code, $include_comments );
This is an object-oriented library which focuses on providing Perl specific methods for accessing the Viddler video service via their API, as documented at: http://developers.viddler.com/documentation/api/
This library currently only supports version 1 of the Viddler API
Along with method specific error codes, all methods may return one of the following error codes upon failure.
Error Codes:
1 An internal error has occurred
2 Bad argument format
3 Unknown argument specified
4 Missing required argument for this method
5 No method specified
6 Unknown method specified
7 API key missing
8 Invalid or unknown API key specified
9 Invalid or expired sessionid
10 Used HTTP method is not allowed for this API method. Try using HTTP POST instead of HTTP GET.
11 Method call not allowed. Your API key security level restricts calling this method.
12 API key disabled
my $video = Viddler->new( apikey => $key, username => $username, password => $passwd );
Instantiates an object which established the basic connection to the API, including requesting and setting a session id.
Gets and sets a sessionid for an authenticated Viddler account. Returned sessionid is valid for 5 minutes (may change in the future). Every method request which contains valid sessionid, renews its validity time.
$video->users_auth;
No required parameters, we use the username and password defined at object's creation
Additional options parameters include:
* get_record_token: If set to "1" response will also include recordToken
Returns 1 ( true ) if successful and a Viddler error code if unsuccessful
Additional Error Codes:
101 Username not found.
102 This account has been suspended.
103 Password incorrect for this username.
Creates a Viddler account. Note: This method is restricted to only qualified API keys.
$video->users_register( $user, $email, $fname, $lname, $password, $question, $answer, $lang, $termsaccepted, $company );
Requires the following parameters:
* user: The chosen Viddler user name
* email: The email address of the user
* fname: The user's first name
* lname: The user's last name
* password: The user's password with Viddler
* question: The text of the user's secret question
* answer: The text of the answer to the secret question
* lang: The language of the user for the account
* termsaccepted: "1" indicates the user has accepted Viddler's terms and conditions
* company: The user's company affiliation
Returns the created username as a string, if successful. Returns an error code if unsuccessful.
104 Terms of Service not accepted by user.
105 Username already in use.
106 Email address already in use.
Retrieves the public parts of a user profile.
$video->users_getProfile( $user );
None
Returns a hash of an array of user's public profile information
Updates authenticated user profile data
$video->users_setProfile( $first_name, $last_name, $about_me, $birthday, $gender, $company, $city );
* first_name: User's first name. 20 characters max
* last_name: User's last name. 20 characters max
* about_me: About the user. No length limitation
* birthdate: User's birthday in yyyy-mm-dd format
* gender: User's gender, either "m" for male or "f" for female
* company: User's company. 100 characters max
* city: User's city. 250 characters max. Currently this is the only address field supported by Viddler, so you may provide more information than just city.
Note: Arguments not sent, won't update the profile. To remove any information from profile just send empty parameter value.
Returns a hash of an array of user's public profile information, including updated information
Search Viddler people (or Viddler users). This method can also be used to search through people that are active and also a Viddler user's friends.
$video->users_search( $type, $query, $page, $per_page );
* type: The type of search (e.g. "everybody", "friends", "active"
* query: What to search for (e.g. "New York City", "Paul Weinstein", or "Photographers")
* page: The "page number" of results to retrieve (e.g. 1, 2, 3)
* per_page: The number of results to retrieve per page (maximum 100). If not specified, the default value equals 20
Returns a hash of an array of search results
Sets user account options. Currently only partners options are supported. More of them later!
$video->users_setOptions( $show_account, $tagging_enabled, $commenting_enabled, $show_related_videos, $embedding_enabled, $clicking_through_enabled, $email_this_enabled, $trackbacks_enabled, $favourites_enabled, $custom_logo_enabled );
* show_account: "1", "0" - Show/hide your account in Viddler. If you set it to "0" both your account and your videos won't be visible on viddler.com site
* tagging_enabled: "1", "0" - Enable/disable tagging on all your videos
* commenting_enabled: "1", "0" - Enable/disable commenting on all your videos
* show_related_videos: "1", "0" - Show/hide related videos on all your videos
* embedding_enabled: "1", "0" - Enable/disable embedding of off all your videos
* clicking_through_enabled: "1", "0" - Enable/disable redirect to Viddler while clicking on embedded player
* email_this_enabled: "1", "0" - Enable/disable email this option on all your videos
* trackbacks_enabled: "1", "0" - Enable/disable trackbacks on all your videos
* favourites_enabled: "1", "0" - Enable/disable favorites on all your videos
* custom_logo_enabled: "1", "0" - Enable/disable custom logo on all your videos. Note: that logo itself must be send to viddler manually.
Returns an integer representing the number of options actually updated
Gets and returns the current version of the Viddler API.
$video->api_getInfo;
Returns current API version as a string
Generate token for embedded recorder
$video->videos_getRecordToken;
Returns a record token as a string
There are two possible solutions for video upload via API call. First one is regular viddler.videos.upload API call. When upload call to this method is received it scans the request and proxies it to best possible upload server. Everything is done in the background and doesn't require any additional client side interaction. Disadvantage of this solution is that the upload will go through multiple servers before reaching its final location. This may cause some slowness in certain situations (API nodes overload etc).
To prevent this you may use second (preferred) solution. Call viddler.videos.prepareUpload method which will assign the best possible upload node for you. After reading the response use "endpoint" tag value as new API endpoint for viddler.videos.upload method call instead of standard http://api.viddler.com/rest/v1/ endpoint.
This method is available since API version 1.3.0.
$video->videos_prepareUpload;
Returns a endpoint as a string for videos_upload method
Uploads a video to a user's account on Viddler site.
Make sure "file" part is sent as the last part of a request. Your upload request will be validated before actual file will be read.
For better videos uploads performance consider using viddler.videos.prepareUpload method which will assign new, one time use API endpoint for video upload call.
* title: The video's title
* tags: Tags for the video. Separate each tag with a space. To join two words together in one tag, use double quotes.
* description: The video description.
* make_public: Use "1" for true and "0" for false to choose whether or not the video goes public when uploaded.
* file: The video file.
* bitrate: (in kilobits per second) The bitrate to encode the current video at, rather than the account default. E.g. 400, 700, or 1500. Note: This option is not available for all accounts.
Returns a hash of an array of the successfully uploaded video's details
Returns the status of a video uploaded through the API
$video->videos_getStatus( $video_id );
* video_id: The ID of the video to get information for. The video ID is a value that's returned by videos_upload.
Returns a status code as a string
Status Codes:
1 Video waiting for encode
2 Video encoding
3 Video did not encoded (encoding error)
4 Video ready
5 Video deleted
Displays the details for a video
* add_embed_code: Include video embed code in response ("1" or "0", default is "0")
* include_comments: Include comments in response ("1" or "0", default: "1")
Returns a hash of an array of the video's details if successful, a Viddler error code if unsuccessful
Notes:
* All possible permission levels in result set are: public, shared_all, shared and private
* Only /video/permissions/view node may contain secreturl node
* Only shared permission level may contain user and list subnodes
100 Video could not be found
$video->videos_getByDetailsByUrl( $video_url );
* video_url: The complete Viddler video URL
Returns a hash of an array of the video's details
Updated video details
$video->videos_setByDetails( $video_id, $title, $description, $tags, $view_perm, $view_users, $view_use_secret, $embed_perm, $embed_users, $commenting_users, $tagging_perm, $tagging_users, $download_perm, $download_users );
* video_id: The ID of the video which you want to update
* title: Video title - 500 characters max
* description: Video description
* tags: List of tags to be set on video. Setting tags will update current tags set (both timed and global video tags). To set timed tag use formattagname[timestamp_in_ms] as tagname. For example - usingtag1,tag2,tag3[2500] will set 2 global and 1 timed tag at 2.5s
* view_perm: View permission. Can be set to public, shared_all, shared or private
* view_users: List of users which may view this video if view_perm is set to shared. Only your viddler friends are allowed here. If you provide multiple usernames - non valid viddler friends usernames will be ignored.
* view_use_secret: If view_perm is set to non public value, you may activate secreturl for your video. If you want to enable or regenerate secreturl pass "1" as parameter value. If you want to disable secreturl pass "0" as parameter value.
* embed_perm: Embedding permission. Supported permission levels are the same as forview_perm. This and all permissions below cannot be less restrictive thanview_perm. You cannot set it to public if view_perm is for example shared.
* embed_users: Same as view_users. If view_perm is shared, this list cannot contain more users than view_users. Invalid usernames will be removed.
* commenting_perm: Commenting permission. Description is the same as for embed_perm
* commenting_users: Same as embed_users.
* tagging_perm: Tagging permission. Description is the same as for embed_perm
* tagging_users: Same as embed_users.
* download_perm: Download permission. Description is the same as for embed_perm
* download_users: Same as embed_users.
Note: Invalid arguments will be ignored. All lists are comma or space separated.
Returns a hash of an array of the video's details, including updated details, if successful. Returns a Viddler error code if unsuccessful.
107 Wrong privileges
Set permalink on videos you own. Permalink is used by our flash player. When a user clicks on a video while it is played, he will be redirected to permalink url defined on a video.
$video->videos_setPermalink( $video_id, $permalink );
* video_id: The ID of the video to get information for. This is the ID that's returned by videos_upload.
* permalink: URL address to your page - max 250 characters long.
Note: To reset a permalink back to its Viddler.com default - simply supply an empty permalink argument.
Returns 0 ( false ) if unsuccessful and 1 ( true ) if successful
Choose a thumbnail based on a moment in time in a video. This feature will select the nearest keyframe to the point given and create a new thumbnail.
Due to the caching methods of Viddler's service, it will take a few minutes for the new thumbnail to propagate to our entire network.
$video->videos_setThumbnail( $video_id, $timepoint, $file );
* timepoint: Time in seconds from 0 to video length (int).
* file: An image file to use as the static thumbnail. JPG, GIF, PNG supported.
* Invalid arguments will be ignored
* Time point must be in seconds and be a valid integer.
* To improve thumbnail generation increase the number of keyframes in the video uploaded.
* Due to caching, a new thumbnail make take a few minutes to propagate throughout the network.
* If both timepoint and file are sent, timepoint is ignored.
* Image files should be the same dimensions as the video. Larger image files will be automatically scaled down.
* Max thumbnail size is 400 KB. Anything larger results in Error 200.
Returns a hash of an array of URL's for accessing various thumbanil image sizes
Gets and returns results of a search of Viddler videos and people.
$video->videos_search( $type, $query, $page, $per_page );
* type: The type of search (e.g. "myvideos", "friendsvideos", "allvideos", "relevant", "recent", "popular", "timedtags", "globaltags". (The "timedtags" and "globetags" sorting argument should be used in conjunction with an actual tag being given for the query argument.))
* query: What to search for (e.g. "iPhone", "Pennsylvania", or "Windows XP")
* page: The "page number" of results to retrieve (e.g. 1, 2, 3).
* per_page: The number of results to retrieve per page (maximum 100). If not specified, the default value equals 20.
Gets and returns a lists of all videos that were uploaded by the specified user.
$video->videos_getByUser( $user, page, $per_page, $tags, $sort );
* user: The chosen Viddler user name. You can provide multiple coma separated Viddler usernames
* page: The of results to retrieve (e.g. 1, 2, 3).
* tags: The tags you would like to filter your query by.
* sort: How you would like to sort your query (views-asc,views-desc,uploaded-asc,uploaded-desc)
Lists all videos that have the specified tag.
$video->videos_getByTag( $tag, $page, $per_page, $sort );
* tag The tag to search for
Returns a hash of an array of details for videos with a matching tag
Lists currently featured videos
$video->videos_getFeatured;
Returns a hash of an array of details for videos featured by Viddler
Deletes a video associated with a users account.
$video->videos_delete( $video_id );
Paul Weinstein, <pdw at weinstein.org>
<pdw at weinstein.org>
Please report any bugs or feature requests to bug-webservice-viddler at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WebService-Viddler. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-webservice-viddler at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc WebService::Viddler
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=WebService-Viddler
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/WebService-Viddler
CPAN Ratings
http://cpanratings.perl.org/d/WebService-Viddler
Search CPAN
http://search.cpan.org/dist/WebService-Viddler/
Copyright 2010 Paul Weinstein.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
To install WebService::Viddler, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::Viddler
CPAN shell
perl -MCPAN -e shell install WebService::Viddler
For more information on module installation, please visit the detailed CPAN module installation guide.