File Coverage

blib/lib/WebService/Viddler.pm

Criterion	Covered	Total	%
statement	16	18	88.8
branch			n/a
condition			n/a
subroutine	6	6	100.0
pod			n/a
total	22	24	91.6

package WebService::Viddler;

use strict;
use warnings;

use HTTP::Request::Common;
use LWP::UserAgent;
use LWP::Simple;
use XML::Simple;

=head1 NAME

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

=head1 VERSION

Version 0.10

=cut

our $VERSION = "0.10";

### To Do
#
# Complete support of all API methods
# Process/Return Viddler error codes for all method calls
# Document common error codes and method specific error codes
# Validation/Error Handling of parameters/results
# Add SSL option for methods such as users_auth
#
####

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

=head1 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

=head2 Methods

=head3 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.

=cut

# The constructor of an object is called new() by convention.

sub new {

    my ( $class, %args ) = @_;
    my $new = bless {

        _apiURL       => 'http://api.viddler.com/rest/v1/',
        _sessionID    => undef,
        _record_token => undef,
        %args

    }, $class;

    # Get a sessionid
    my $result = $new->users_auth;

    if ( $result ne "1" ) {

        warn "Viddler Error: " . $result;

    }

    return $new;

}

=head3 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.

=cut

sub users_auth {

    my ( $self, $get_record_token ) = @_;

    if ( ( !defined $get_record_token ) || ( $get_record_token ne "1" ) ) {

        $get_record_token = "";

    }

    my $xml = new XML::Simple;
    my $content =
        get $self->{_apiURL}
      . "?method=viddler.users.auth&api_key="
      . $self->{apiKey}
      . "&user="
      . $self->{username}
      . "&password="
      . $self->{password}
      . "&get_record_token="
      . $get_record_token;
    my $results = $xml->XMLin($content);

    if ( defined $results->{'code'} ) {

        return $results->{'code'};

    }
    else {

        $self->{_sessionID} = $results->{'sessionid'};

        if ( defined $results->{'get_record_token'} ) {

            $self->{_recordToken} = $results->{'record_token'};

        }

        if ( defined( $self->{_sessionID} ) ) {

            return 1;

        }

    }

}

=head3 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.

=cut

sub users_register( $$$$$$$$$ ) {

    my (
        $self,  $user,          $email,    $fname,
        $lname, $password,      $question, $answer,
        $lang,  $termsaccepted, $company
    ) = @_;

    my $xml = new XML::Simple;

    if ( !defined $company ) {

        $company = "";

    }

    my $content =
        get $self->{_apiURL}
      . "?method=viddler.users.register&api_key="
      . $self->{apiKey}
      . "&user="
      . $user
      . "&email="
      . $email
      . "&fname="
      . $fname
      . "&lname="
      . $lname
      . "&password="
      . $password
      . "&question="
      . $question
      . "&answer="
      . $answer
      . "&lang="
      . $lang
      . "&termsaccepted="
      . $termsaccepted
      . "&company="
      . $company;
    my $results = $xml->XMLin($content);

    if ( defined $results->{'code'} ) {

        return $results->{'code'};

    }
    else {

        return $results->{'username'};

    }

}

=head3 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

=cut

sub users_getProfile( $ ) {

    my ( $self, $user ) = @_;

    my $xml = new XML::Simple;
    my $content =
        get $self->{_apiURL}
      . "?method=viddler.users.getProfile&api_key="
      . $self->{apiKey}
      . "&user="
      . $user;
    my $results = $xml->XMLin($content);
    return $results;

}

=head3 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

=cut

sub users_setProfile {

    my ( $self, $first_name, $last_name, $about_me, $birthday, $gender,
        $company, $city )
      = @_;

    my $xml = new XML::Simple;
    my $ua  = new LWP::UserAgent;

    my $content =
        "method=viddler.users.setProfile"
      . "&api_key="
      . $self->{apiKey}
      . "&sessionid="
      . $self->{_sessionID};

    if ( defined $first_name ) {

        $content .= "&first_name=" . $first_name;

    }

    if ( defined $last_name ) {

        $content .= "&last_name=" . $last_name;

    }

    if ( defined $about_me ) {

        $content .= "&about_me=" . $about_me;

    }

    if ( defined $birthday ) {

        $content .= "&birthday=" . $birthday;

    }

    if ( defined $gender ) {

        $content .= "&gender=" . $gender;

    }

    if ( defined $company ) {

        $content .= "&company=" . $company;

    }

    if ( defined $city ) {

        $content .= "&city=" . $city;

    }

    my $request = POST $self->{_apiURL},
      Content_Type => 'application/x-www-form-urlencoded',
      Content      => $content;

    my $results = $xml->XMLin( $ua->request($request)->content );
    return $results;

}

=head3 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

=cut

sub users_search( $$ ) {

    my ( $self, $type, $query, $page, $per_page ) = @_;

    if ( !defined $page ) {

        $page = "";

    }

    if ( !defined $per_page ) {

        $per_page = "";

    }

    my $xml = new XML::Simple;
    my $content =
        get $self->{_apiURL}
      . "?method=viddler.users.search&api_key="
      . $self->{apiKey}
      . "&sessionid="
      . $self->{_sessionID}
      . "&type="
      . $type
      . "&query="
      . $query
      . "&page="
      . $page
      . "&per_page="
      . $per_page;
    my $results = $xml->XMLin($content);
    return $results;

}

=head3 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

=cut

sub users_setOptions {

    my (
        $self,                     $show_account,
        $tagging_enabled,          $commenting_enabled,
        $show_related_videos,      $embedding_enabled,
        $clicking_through_enabled, $email_this_enabled,
        $trackbacks_enabled,       $favourites_enabled,
        $custom_logo_enabled
    ) = @_;

    my $xml = new XML::Simple;

    if ( !defined $show_account ) {

        $show_account = "";

    }

    if ( !defined $tagging_enabled ) {

        $tagging_enabled = "";

    }

    if ( !defined $commenting_enabled ) {

        $commenting_enabled = "";

    }

    if ( !defined $show_related_videos ) {

        $show_related_videos = "";

    }

    if ( !defined $embedding_enabled ) {

        $embedding_enabled = "";

    }

    if ( !defined $clicking_through_enabled ) {

        $clicking_through_enabled = "";

    }

    if ( !defined $email_this_enabled ) {

        $email_this_enabled = "";

    }

    if ( !defined $trackbacks_enabled ) {

        $trackbacks_enabled = "";

    }

    if ( !defined $favourites_enabled ) {

        $favourites_enabled = "";

    }

    if ( !defined $custom_logo_enabled ) {

        $custom_logo_enabled = "";

    }

    my $content =
        get $self->{_apiURL}
      . "?method=viddler.users.setOptions&api_key="
      . $self->{apiKey}
      . "&sessionid="
      . $self->{_sessionID}
      . "&show_account="
      . $show_account
      . "&tagging_enabled="
      . $tagging_enabled
      . "&commenting_enabled"
      . $commenting_enabled
      . "&show_related_videos="
      . $show_related_videos
      . "&embedding_enabled="
      . $embedding_enabled
      . "&clicking_ithrough_enabled="
      . $clicking_through_enabled
      . "&email_this_enabled="
      . $email_this_enabled
      . "&trackbacks_enabled="
      . $trackbacks_enabled
      . "&favourites_enabled="
      . $favourites_enabled
      . "&custom_logo_enabled="
      . $custom_logo_enabled;
    my $results = $xml->XMLin($content);
    return $results->{'updated'};

}

=head3 api_getInfo

Gets and returns the current version of the Viddler API.

$video->api_getInfo;

Returns current API version as a string

=cut

sub api_getInfo {

    my ($self) = @_;

    my $xml = new XML::Simple;
    my $content =
        get $self->{_apiURL}
      . "?method=viddler.api.getInfo&api_key="
      . $self->{apiKey};
    my $results = $xml->XMLin($content);
    return $results->{'version'};

}

=head3 videos_getRecordToken

Generate token for embedded recorder

$video->videos_getRecordToken;

Returns a record token as a string

=cut

sub videos_getRecordToken {

    my ($self) = @_;

    my $xml = new XML::Simple;
    my $content =
        get $self->{_apiURL}
      . "?method=viddler.videos.getRecordToken&api_key="
      . $self->{apiKey}
      . "&sessionid="
      . $self->{_sessionID};
    my $results = $xml->XMLin($content);
    return $results->{'record_token'};

}

=head3 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

=cut

sub videos_prepareUpload {

    my ($self) = @_;

    my $xml = new XML::Simple;
    my $content =
        get $self->{_apiURL}
      . "?method=viddler.videos.prepareUpload&api_key="
      . $self->{apiKey}
      . "&sessionid="
      . $self->{_sessionID};
    my $results = $xml->XMLin($content);
    return $results->{'endpoint'};

}

=head3 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

=cut

sub videos_upload( $$$$$ ) {

    my ( $self, $title, $tags, $description, $make_public, $file, $bitrate ) =
      @_;

    my $xml = new XML::Simple;
    my $ua  = new LWP::UserAgent;

    my $request = POST $self->{_apiURL},
      Content_Type => 'multipart/form-data',
      Content      => [
        method      => 'viddler.videos.upload',
        api_key     => $self->{apiKey},
        sessionid   => $self->{_sessionID},
        title       => $title,
        tags        => $tags,
        description => $description,
        make_public => $make_public,
        file        => [$file],
        bitrate     => $bitrate
      ];

    my $results = $xml->XMLin( $ua->request($request)->content );
    return $results;

}

=head3 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

=cut

sub videos_getStatus( $ ) {

    my ( $self, $video_id ) = @_;

    my $xml = new XML::Simple;
    my $content =
        get $self->{_apiURL}
      . "?method=viddler.videos.getStatus&api_key="
      . $self->{apiKey}
      . "&sessionid="
      . $self->{_sessionID}
      . "&video_id="
      . $video_id;
    my $results = $xml->XMLin($content);
    return $results->{'statuscode'};

}

=head3 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

=cut

sub videos_getDetails( $ ) {

    my ( $self, $video_id, $add_embed_code, $include_comments ) = @_;

    my $xml = new XML::Simple;

    if ( !defined $add_embed_code ) {

        $add_embed_code = "0";

    }

    if ( !defined $include_comments ) {

        $include_comments = "1";

    }

    my $content =
        get $self->{_apiURL}
      . "?method=viddler.videos.getDetails&api_key="
      . $self->{apiKey}
      . "&sessionid="
      . $self->{_sessionID}
      . "&video_id="
      . $video_id
      . "&add_embed_code="
      . $add_embed_code
      . "&include_comments="
      . $include_comments;
    my $results = $xml->XMLin($content);

    if ( defined $results->{'code'} ) {

        return $results->{'code'};

    }
    else {

        return $results;

    }

}

=head3 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

=cut

sub videos_getDetailsByUrl( $ ) {

    my ( $self, $video_url ) = @_;

    my $xml = new XML::Simple;
    my $content =
        get $self->{_apiURL}
      . "?method=viddler.videos.getDetailsByUrl&api_key="
      . $self->{apiKey}
      . "&sessionid="
      . $self->{_sessionID} . "&url="
      . $video_url;
    my $results = $xml->XMLin($content);

    if ( defined $results->{'code'} ) {

        return $results->{'code'};

    }
    else {

        return $results;

    }

}

=head3 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

=cut

sub videos_setDetails( $ ) {

    my (
        $self,         $video_id,        $title,
        $description,  $tags,            $view_perm,
        $view_users,   $view_use_secret, $embed_perm,
        $embed_users,  $commenting_perm, $commenting_users,
        $tagging_perm, $tagging_users,   $download_perm,
        $download_users
    ) = @_;

    my $xml = new XML::Simple;
    my $ua  = new LWP::UserAgent;

    my $content =
        "method=viddler.users.setDetails"
      . "&api_key="
      . $self->{apiKey}
      . "&sessionid="
      . $self->{_sessionID}
      . "&video_id="
      . $video_id;

    if ( defined $title ) {

        $content .= "&title=" . $title;

    }

    if ( defined $description ) {

        $content .= "&description=" . $description;

    }

    if ( defined $tags ) {

        $content .= "&tags=" . $tags;

    }

    if ( defined $view_perm ) {

        $content .= "&view_perm=" . $view_perm;

    }

    if ( defined $view_users ) {

        $content .= "&view_users=" . $view_users;

    }

    if ( defined $view_use_secret ) {

        $content .= "&view_use_secret=" . $view_use_secret;

    }

    if ( defined $embed_perm ) {

        $content .= "&embed_perm=" . $embed_perm;

    }

    if ( defined $embed_users ) {

        $content .= "&embed_users=" . $embed_users;

    }

    if ( defined $commenting_perm ) {

        $content .= "&commenting_perm=" . $commenting_perm;

    }

    if ( defined $commenting_users ) {

        $content .= "&commenting_users=" . $commenting_users;

    }

    if ( defined $tagging_perm ) {

        $content .= "&tagging_perm=" . $tagging_perm;

    }

    if ( defined $tagging_users ) {

        $content .= "&tagging_users=" . $tagging_users;

    }

    if ( defined $download_perm ) {

        $content .= "&download_perm=" . $download_perm;

    }

    if ( defined $download_users ) {

        $content .= "&download_users=" . $download_users;

    }

    my $request = POST $self->{_apiURL},
      Content_Type => 'application/x-www-form-urlencoded',
      Content      => $content;

    my $results = $xml->XMLin( $ua->request($request)->content );

    if ( defined $results->{'code'} ) {

        return $results->{'code'};

    }
    else {

        return $results;

    }

}

=head3 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

=cut

sub videos_setPermalink( $$ ) {

    my ( $self, $video_id, $permalink ) = @_;

    my $xml = new XML::Simple;
    my $content =
        get $self->{_apiURL}
      . "?method=viddler.videos.setPermalink&api_key="
      . $self->{apiKey}
      . "&sessionid="
      . $self->{_sessionID}
      . "&video_id="
      . $video_id
      . "&permalink="
      . $permalink;
    my $results = $xml->XMLin($content);

    if ( defined( $results->{'success'} ) ) {

        return 1;

    }
    else {

        return 0;

    }

}

=head3 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

=cut

sub videos_setThumbnail( $$ ) {

    my ( $self, $video_id, $timepoint, $file ) = @_;

    my $xml = new XML::Simple;
    my $ua  = new LWP::UserAgent;

    my $request = POST $self->{_apiURL},
      Content_Type => 'multipart/form-data',
      Content      => [
        method    => 'viddler.videos.setThumbnail',
        api_key   => $self->{apiKey},
        sessionid => $self->{_sessionID},
        video_id  => $video_id,
        timepoint => $timepoint,
        file      => [$file]
      ];

    my $results = $xml->XMLin( $ua->request($request)->content );
    return $results;

}

=head3 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

=cut

sub videos_search( $$ ) {

    my ( $self, $type, $query, $page, $per_page ) = @_;

    my $xml = new XML::Simple;

    if ( !defined $page ) {

        $page = "";

    }

    if ( !defined $per_page ) {

        $per_page = "";

    }

    my $content =
        get $self->{_apiURL}
      . "?method=viddler.videos.search&api_key="
      . $self->{apiKey}
      . "&type="
      . $type
      . "&query="
      . $query
      . "&page="
      . $page
      . "&per_age="
      . $per_page
      . "&sessionid="
      . $self->{_sessionID};
    my $results = $xml->XMLin($content);
    return $results;

}

=head3 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

=cut

sub videos_getByUser( $ ) {

    my ( $self, $user, $page, $per_page, $tags, $sort ) = @_;

    my $xml = new XML::Simple;

    if ( !defined $page ) {

        $page = "";

    }

    if ( !defined $per_page ) {

        $per_page = "";

    }

    if ( !defined $tags ) {

        $tags = "";

    }

    if ( !defined $sort ) {

        $sort = "";

    }

    my $content =
        get $self->{_apiURL}
      . "?method=viddler.videos.getByUser&api_key="
      . $self->{apiKey}
      . "&sessionid="
      . $self->{_sessionID}
      . "&user="
      . $user
      . "&page="
      . $page
      . "&per_age="
      . $per_page
      . "&tags="
      . $tags
      . "&sort="
      . $sort;
    my $results = $xml->XMLin($content);
    return $results;

}

=head3 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

=cut

sub videos_getByTag( $ ) {

    my ( $self, $tag, $page, $per_page, $sort ) = @_;

    my $xml = new XML::Simple;

    if ( !defined $page ) {

        $page = "";

    }

    if ( !defined $per_page ) {

        $per_page = "";

    }

    if ( !defined $sort ) {

        $sort = "";

    }

    my $content =
        get $self->{_apiURL}
      . "?method=viddler.videos.getByTag&api_key="
      . $self->{apiKey} . "&tag="
      . $tag
      . "&page="
      . $page
      . "&per_page="
      . $per_page
      . "&sort="
      . $sort;
    my $results = $xml->XMLin($content);
    return $results;

}

=head3 videos_getFeatured

Lists currently featured videos

$video->videos_getFeatured;

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

=cut

sub videos_getFeatured( ) {

    my ($self) = @_;

    my $xml = new XML::Simple;
    my $content =
        get $self->{_apiURL}
      . "?method=viddler.videos.getFeatured&api_key="
      . $self->{apiKey};
    my $results = $xml->XMLin($content);
    return $results;

}

=head3 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

=cut

sub videos_delete( $ ) {

    my ( $self, $video_id ) = @_;

    my $xml = new XML::Simple;
    my $content =
        get $self->{_apiURL}
      . "?method=viddler.videos.delete&api_key="
      . $self->{apiKey}
      . "&sessionid="
      . $self->{_sessionID}
      . "&video_id="
      . $video_id;
    my $results = $xml->XMLin($content);

    if ( defined( $results->{'success'} ) ) {

        return 1;

    }
    else {

        return 0;

    }

}

=head1 AUTHOR

Paul Weinstein, C<<  >>

=head1 BUGS

Please report any bugs or feature requests to C, or through
the web interface at L.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

=head1 SUPPORT

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

    perldoc WebService::Viddler


You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L

=item * AnnoCPAN: Annotated CPAN documentation

L

=item * CPAN Ratings

L

=item * Search CPAN

L

=back


=head1 ACKNOWLEDGEMENTS


=head1 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.


=cut

1;    # End of WebService::Viddler
__END__