Paul Weinstein > WebService-Viddler-0.10 > WebService::Viddler

Download:
WebService-Viddler-0.10.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.10   Source  

NAME ^

WebService::Viddler - An encapsulation of the Viddler video platform in Perl

VERSION ^

Version 0.10

SYNOPSIS ^

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 );

DESCRIPTION ^

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

Methods

new

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.

users_auth

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.

users_register

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

Additional options parameters include:

* company: The user's company affiliation

Returns the created username as a string, if successful. Returns an error code if unsuccessful.

Additional Error Codes:

104 Terms of Service not accepted by user.

105 Username already in use.

106 Email address already in use.

users_getProfile

Retrieves the public parts of a user profile.

$video->users_getProfile( $user );

Requires the following parameters:

* user: The chosen Viddler user name

Additional options parameters include:

None

Returns a hash of an array of user's public profile information

users_setProfile

Updates authenticated user profile data

$video->users_setProfile( $first_name, $last_name, $about_me, $birthday, $gender, $company, $city );

Requires the following parameters:

None

Additional options parameters include:

* 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

users_search

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 );

Requires the following parameters:

* type: The type of search (e.g. "everybody", "friends", "active"

* query: What to search for (e.g. "New York City", "Paul Weinstein", or "Photographers")

Additional options parameters include:

* 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

users_setOptions

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 );

Requires the following parameters:

None

Additional options parameters include:

* 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

api_getInfo

Gets and returns the current version of the Viddler API.

$video->api_getInfo;

Returns current API version as a string

videos_getRecordToken

Generate token for embedded recorder

$video->videos_getRecordToken;

Returns a record token as a string

videos_prepareUpload

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

videos_upload

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.

$video->videos_upload( $title, $tags, $description, $make_public, $file, $bitrate );

Requires the following parameters:

* 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.

Additional options parameters include:

* 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

videos_getStatus

Returns the status of a video uploaded through the API

$video->videos_getStatus( $video_id );

Requires the following parameters:

* video_id: The ID of the video to get information for. The video ID is a value that's returned by videos_upload.

Additional options parameters include:

None

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

videos_getDetails

Displays the details for a video

$video->videos_getDetails( $video_id, $add_embed_code, $include_comments );

Requires the following parameters:

* video_id: The ID of the video to get information for. The video ID is a value that's returned by videos_upload.

Additional options parameters include:

* 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

Additional Error Codes:

100 Video could not be found

videos_getDetailsByUrl

Displays the details for a video

$video->videos_getByDetailsByUrl( $video_url );

Requires the following parameters:

* video_url: The complete Viddler video URL

Additional options parameters include:

None

Returns a hash of an array of the video's details

Additional Error Codes:

2 Bad argument format

100 Video could not be found

videos_setDetails

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 );

Requires the following parameters:

* video_id: The ID of the video which you want to update

Additional options parameters include:

* 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.

Additional Error Codes:

100 Video could not be found

107 Wrong privileges

videos_setPermalink

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 );

Requires the following parameters:

* 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.

Additional options parameters include:

None

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

videos_setThumbnail

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 );

Requires the following parameters:

* video_id: The ID of the video which you want to update

* timepoint: Time in seconds from 0 to video length (int).

* file: An image file to use as the static thumbnail. JPG, GIF, PNG supported.

Additional options parameters include:

None

Notes:

* 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

videos_search

Gets and returns results of a search of Viddler videos and people.

$video->videos_search( $type, $query, $page, $per_page );

Requires the following parameters:

* 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")

Additional options parameters include:

* 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

videos_getByUser

Gets and returns a lists of all videos that were uploaded by the specified user.

$video->videos_getByUser( $user, page, $per_page, $tags, $sort );

Requires the following parameters:

* user: The chosen Viddler user name. You can provide multiple coma separated Viddler usernames

Additional options parameters include:

* page: The 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.

* 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)

Returns a hash of an array of search results

videos_getByTag

Lists all videos that have the specified tag.

$video->videos_getByTag( $tag, $page, $per_page, $sort );

Requires the following parameters:

* tag The tag to search for

Additional options parameters include:

* 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.

* sort: How you would like to sort your query (views-asc,views-desc,uploaded-asc,uploaded-desc)

Returns a hash of an array of details for videos with a matching tag

videos_getFeatured

Lists currently featured videos

$video->videos_getFeatured;

Returns a hash of an array of details for videos featured by Viddler

videos_delete

Deletes a video associated with a users account.

$video->videos_delete( $video_id );

Requires the following parameters:

* video_id: The ID of the video to get information for. This is the ID that's returned by videos_upload.

Additional options parameters include:

None

Returns 0 ( false ) if unsuccessful and 1 ( true ) if successful

AUTHOR ^

Paul Weinstein, <pdw at weinstein.org>

BUGS ^

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.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc WebService::Viddler

You can also look for information at:

ACKNOWLEDGEMENTS ^

LICENSE AND COPYRIGHT ^

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.

syntax highlighting: