API:EPrints/Plugin/Convert/Thumbnails: Difference between revisions

Latest revision as of 09:56, 22 January 2013

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects

API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki

NAME

EPrints::Plugin::Convert::Thumbnails - thumbnail-sized versions of audio/video/images

The Thumbnail How-to may also be useful: How to customise thumbnails

SYNOPSIS

use EPrints;

# enable audio previews
$c->{plugins}->{'Convert::Thumbnails'}->{params}->{audio} = 1;
# disable video previews
$c->{plugins}->{'Convert::Thumbnails'}->{params}->{video} = 0;

# enable audio_*/video_* previews
$c->{thumbnail_types} = sub {
	my( $list, $repo, $doc ) = @_;

	push @$list, qw( audio_mp4 audio_ogg video_mp4 video_ogg );
};

...

my $plugin = $session->plugin( "Convert" );
my %available = $plugin->can_convert( $doc );
$plugin = $available{"thumbnail_video"}->{plugin};
$new_doc = $plugin->convert( $doc, "thumbnail_video" );

DESCRIPTION

Conversion of images, videos and audio into preview/thumbnail versions.

This plugin wraps the ImageMagick convert and ffmpeg tools.

Testing Audio and Video Conversion

When files are uploaded to EPrints a file format identification process occurs. This is based on the EP_TRIGGER_MEDIA_INFO callbacks. A set of callbacks are provided by lib/cfg.d/media_info.pl. To customise these copy the file to your repository's cfg.d/ directory.

This plugin relies on the media info added by the file format identification. To check this is working export the EPrint as XML and check for a <media> entry in your document:

  ./bin/export [archiveid] eprint XML [eprintid]

At any time you can re-run the file format identification by using redo_mime_type in epadmin:

  ./bin/epadmin redo_mime_type [archiveid] eprint [eprintid] --verbose

If ffprobe is configured correctly you should see it being called for each document.

Finally, to regenerate thumbnails do:

  ./bin/epadmin redo_thumbnails [archiveid] [eprintid] --verbose

PARAMETERS

These parameters can be set through the plugins.pl configuration file. You must also configure the executables locations for convert and ffmpeg in EPrints::SystemSettings.

convert_formats = { ext => mime_type }

Define the formats supported for input by the call_convert() method.

ffmpeg_formats = { ext => mime_type }

Define the formats supported for input by the call_ffmpeg() method.

sizes = { size => [$w, $h] }

Define the size of thumbnails that can be generated e.g. "small => [66,50]". The image dimensions generated may be smaller than those specified if the aspect ratio of the source document is different.

Images are output in 8-bit paletted PNG.

video = 1

Enable video previews.

audio = 1

Enable audio previews.

video_height = "480"

Video preview vertical lines.

audio_sampling = "44100"

Audio frequency sampling rate in Hz.

audio_bitrate = "96k"

Audio bit rate in kb/s

audio_codec = "libfaac"

ffmpeg compiled-in AAC codec name.

frame_rate = "10.00"

Video frame rate in fps.

video_codec = "h264"

ffmpeg compiled-in H.264 codec name (may be libx264 on some platforms).

video_rate = "1500k"

Video bit rate in kilobits.

call_convert = sub( $plugin, $dst, $doc, $src, $geom, $size )

See call_convert.

call_ffmpeg = sub( $plugin, $dst, $doc, $src, $geom, $size, $offset )

See call_ffmpeg.

METHODS

can_convert

%types = $plugin->can_convert( $doc )

Returns a hash map of types this plugin can convert $doc to.

This may be relatively expensive to do if the plugin has to call an external tool to determine if it can export something.

convert

$new_doc = $plugin->convert( $eprint, $doc, $type )

Request the plugin converts $doc to $type, as returned by can_convert.

export

@filelist = $plugin->export( $dir, $doc, $type )

Request the plugin converts $doc to $type, as returned by can_convert. Outputs the resulting files to $dir and returns their paths (excluding the leading $dir part).

Utility Methods

$ver = $plugin->convert_version()

Returns the MAJOR.MINOR version of ImageMagick.

Returns 0.0 if the version can not be determined.

$ok = $plugin->is_video( $doc )

Returns true if $doc is a video.

$doc = $plugin->intermediate( $doc, $src, $geom, $src )

Attempt to find an intermediate document that we can use to convert from (e.g. make a thumbnail from a preview version).

Returns the original $doc if not intermediate is found.

$plugin->call_convert( $dst, $doc, $src, $geom, $size )

Calls the ImageMagick convert tool to convert $doc into a thumbnail image. Writes the image to $dst. $src is the full path to the main file from $doc. The resulting image should not exceed $geom dimensions ([w,h] array ref).

$size is the thumbnail-defined size (as-in the keys to the sizes parameter).

This method can be overridden with the call_convert parameter.

$plugin->call_ffmpeg( $dst, $doc, $src, $geom, $size, $offset )

Uses the ffmpeg tool to do the image conversion of $doc. $dst is the filename to write to, $src is the filename to read from and $geom is the image dimensions to write.

$size is the thumbnail-defined size (as-in the keys to the sizes parameter or audio or video).

$offset is the time offset to extract (for audio/video). It is an array ref of [HOUR, MINUTE, SECOND, FRAME].

$plugin->export_mp3( $dst, $doc, $src, $rate )

Export $src to $dst in MP3 format at sampling rate $rate.

$plugin->export_audio( $dst, $doc, $src, $container )

Export audio-only $src to $dst in $container format.

Audio is encoded as audio_codec.

$plugin->export_video( $dst, $doc, $src, $container )

Export audio and video $src to $dst in $container format with vertical lines $lines maintaining aspect ratio.

Video is encoded as video_codec.

Audio is encoded as audio_codec.

$plugin->export_cell( $dir, $doc, $src, $geom, $size, $offset )

Export $src to $dst in JPG format in dimensions $geom from offset $offset.

$secs = $plugin->calculate_offset( $duration, $offset )

Translates a seconds or percentage offset into seconds from the start time. If the resulting time is greater than $duration returns $duration.

To specify seconds either use just a number (1234) or append 's' (1234s).

To specify a percentage of $duration append '%' (52%).

AUTHOR

This module is released under the GPLv3 license.

COPYRIGHT

This file is part of EPrints http://www.eprints.org/.

EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.