API:EPrints/Plugin/Convert/Thumbnails

From EPrints Documentation
Revision as of 09:56, 22 January 2013 by Tdb01r (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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%).


SEE ALSO

EPrints::Plugin, EPrints::Plugin::Convert.


AUTHOR

Copyright 2009 Tim Brody <tdb2@ecs.soton.ac.uk>, University of Southampton, UK.

This module is released under the GPLv3 license.


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



Retrieved from ‘https://wiki.eprints.org/w/index.php?title=API:EPrints/Plugin/Convert/Thumbnails&oldid=10705’