API:EPrints/Plugin/Convert/Thumbnails

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.

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

convert_version

$ver = $plugin->convert_version()

Returns the MAJOR.MINOR version of ImageMagick.

Returns 0.0 if the version can not be determined.

is_video

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

Returns true if $doc is a video.

intermediate

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

call_convert

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

call_ffmpeg

$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].

export_mp3

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

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

export_audio

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

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

Audio is encoded as audio_codec.

export_video

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

export_cell

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

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

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