View source for API:EPrints/Plugin/Convert/Thumbnails

<!-- Pod2Wiki=_preamble_ 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
 -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Plugin/Convert/Thumbnails.pm|package_name=EPrints::Plugin::Convert::Thumbnails}}[[Category:API|THUMBNAILS]][[Category:API:EPrints/Plugin/Convert|THUMBNAILS]][[Category:API:EPrints/Plugin/Convert/Thumbnails|THUMBNAILS]]<div><!-- Edit below this comment -->


<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
==NAME==
EPrints::Plugin::Convert::Thumbnails - thumbnail-sized versions of audio/video/images

<!-- Edit below this comment -->

The Thumbnail How-to may also be useful: [[How to customise thumbnails]]
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_synopsis -->
==SYNOPSIS==
<source lang="perl">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" );

</source>

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_description -->
==DESCRIPTION==
Conversion of images, videos and audio into preview/thumbnail versions.

This plugin wraps the ImageMagick ''convert'' and ''ffmpeg'' tools.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_testing_audio_and_video_conversion -->
===Testing Audio and Video Conversion===
When files are uploaded to EPrints a file format identification process occurs. This is based on the <code>EP_TRIGGER_MEDIA_INFO</code> 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 <code>media</code> info added by the file format identification. To check this is working export the EPrint as XML and check for a &lt;media&gt; entry in your document:

<pre>  ./bin/export [archiveid] eprint XML [eprintid]</pre>

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

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

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

Finally, to regenerate thumbnails do:

<pre>  ./bin/epadmin redo_thumbnails [archiveid] [eprintid] --verbose</pre>

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_parameters -->
==PARAMETERS==
These parameters can be set through the '''plugins.pl''' configuration file. You must also configure the '''executables''' locations for <em>convert</em> and <em>ffmpeg</em> in [[API:EPrints/SystemSettings|EPrints::SystemSettings]].

* convert_formats = { ext =&gt; mime_type }
: Define the formats supported for input by the call_convert() method.

* ffmpeg_formats = { ext =&gt; mime_type }
: Define the formats supported for input by the call_ffmpeg() method.

* sizes = { size =&gt; [$w, $h] }
: Define the size of thumbnails that can be generated e.g. "small =&gt; [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"
: <em>ffmpeg</em> compiled-in AAC codec name.

* frame_rate = "10.00"
: Video frame rate in fps.

* video_codec = "h264"
: <em>ffmpeg</em> 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 [[API:EPrints/Plugin/Convert/Thumbnails#call_convert|call_convert]].

* call_ffmpeg = sub( $plugin, $dst, $doc, $src, $geom, $size, $offset )
: See [[API:EPrints/Plugin/Convert/Thumbnails#call_ffmpeg|call_ffmpeg]].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_methods -->
==METHODS==
<!-- Pod2Wiki=head_can_convert -->
===can_convert===

<source lang="perl">%types = $plugin->can_convert( $doc )

</source>
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.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_convert -->
===convert===

<source lang="perl">$new_doc = $plugin->convert( $eprint, $doc, $type )

</source>
Request the plugin converts $doc to $type, as returned by [[API:EPrints/Plugin/Convert/Thumbnails#can_convert|can_convert]].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_export -->
===export===

<source lang="perl">@filelist = $plugin->export( $dir, $doc, $type )

</source>
Request the plugin converts $doc to $type, as returned by [[API:EPrints/Plugin/Convert/Thumbnails#can_convert|can_convert]]. Outputs the resulting files to $dir and returns their paths (excluding the leading $dir part).

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_utility_methods -->
===Utility Methods===
 $ver = $plugin-&gt;convert_version()
Returns the MAJOR.MINOR version of ImageMagick.

Returns 0.0 if the version can not be determined.

 $ok = $plugin-&gt;is_video( $doc )
Returns true if $doc is a video.

 $doc = $plugin-&gt;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-&gt;call_convert( $dst, $doc, $src, $geom, $size )
Calls the ImageMagick <em>convert</em> 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-&gt;call_ffmpeg( $dst, $doc, $src, $geom, $size, $offset )
Uses the <em>ffmpeg</em> 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-&gt;export_mp3( $dst, $doc, $src, $rate )
Export $src to $dst in MP3 format at sampling rate $rate.

 $plugin-&gt;export_audio( $dst, $doc, $src, $container )
Export audio-only $src to $dst in $container format.

Audio is encoded as <em>audio_codec</em>.

 $plugin-&gt;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 <em>video_codec</em>.

Audio is encoded as <em>audio_codec</em>.

 $plugin-&gt;export_cell( $dir, $doc, $src, $geom, $size, $offset )
Export $src to $dst in JPG format in dimensions $geom from offset $offset.

 $secs = $plugin-&gt;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%).

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_see_also -->
==SEE ALSO==
[[API:EPrints/Plugin|EPrints::Plugin]], [[API:EPrints/Plugin/Convert|EPrints::Plugin::Convert]].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_author -->
==AUTHOR==
Copyright 2009 Tim Brody &lt;tdb2@ecs.soton.ac.uk&gt;, University of Southampton, UK.

This module is released under the GPLv3 license.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_copyright -->
==COPYRIGHT==
Copyright 2000-2011 University of Southampton.

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

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=_postamble_ -->
<!-- Edit below this comment -->