Multimedia

Information about the multimedia attached to an EMu record from any module (except the Multimedia module itself) can be retrieved using the IMu::Module class fetch method by specifying one of the following virtual columns.

The following virtual columns return information about a single multimedia attachment of the current record. The information is returned as a hash reference:

• application
• audio
• image
• video

The following virtual columns return information about a set of multimedia attachments of the current record. The information is returned as an array reference. Each array member is a hash reference containing the information for a single multimedia attachment from the set:

• applications
• audios
• images
• multimedia
• videos

All of these virtual columns return the irn, type and format of the Multimedia record attached to the current record. They also act as reference columns to the Multimedia module. This means that other columns from the Multimedia module (including virtual columns) can also be requested from the corresponding Multimedia record, for example:

1. Include the title for all attached multimedia:

   multimedia.MulTitle

2. Include the title for all attached images:

   images.MulTitle

3. Include details about the master multimedia file for all attached images (using the virtual Multimedia module column master):

   images.master

4. Include multiple columns for all attached images:

   images.(master,MulTitle,MulDescription)

5. Include and rename multiple columns for all attached images:

   images.(master,title=MulTitle,description=MulDescription)

Example

This example shows the retrieval of the base information and the title for all multimedia images attached to a parties record:

my $columns = 
[
    'images.MulTitle'
];my $result = $parties->fetch('start', 0, 1, $columns);
foreach my $row (@{$result->{'rows'}})
{
    foreach my $image (@{$row->{'images'}})
    {
        my $irn = $image->{'irn'};
        my $type = $image->{'type'};
        my $format = $image->{'format'};
        my $title = $image->{'MulTitle'};

        printf("irn %d: %s - %s/%s\n", $irn, $title, $type, $format);
    }
}

This will produce output similar to the following:

irn 100105: Signature of Luciano Pavarotti - image/jpeg

irn 100096: Luciano Pavarotti - image/gif

irn 100100: Luciano Pavarotti with Celine Dion - image/gif

irn 100101: Luciano Pavarotti with Natalie Cole - image/gif

irn 100102: Luciano Pavarotti with the Spice Girls - image/gif

Similarly, information about the multimedia files associated with a Multimedia module record can be retrieved using the IMu::Module class fetch method by specifying one of the following virtual columns.

The following virtual columns return information about a single multimedia file from the current Multimedia record. The information is returned as a hash reference:

• master
• resource
• thumbnail

The following virtual columns return information about a set of multimedia files of the current Multimedia record. The information is returned as an array reference. Each array member is a hash reference containing the information for a single multimedia file from the set:

• resolutions
• resources
• supplementary

The master, thumbnail, resolutions and supplementary virtual columns all return the same type of information. That information differs for image and non-image multimedia as follows:

For non-image multimedia they return:

Returns	Details
fileSize	The size of the file in bytes.
identifier	The name of the multimedia file.
index	An integer that specifies the multimedia files position in the list of the master, thumbnail, resolutions and supplementary (in that order) multimedia files numbered from 0.
kind	The kind (master, thumbnail, resolution, or supplementary) of the multimedia.
md5Checksum	The MD5 checksum of the multimedia file.
md5Sum	The same as md5Checksum (included for backwards compatibility).
mimeFormat	The media format.
mimeType	The media type.
size	The same as fileSize (included for backwards compatibility).

For image multimedia they return all of the values specified for non-image multimedia and also include:

Returns	Details
bitsPerPixel	The colour depth of the image.
colourSpace	The colour space of the image.
compression	The type of compression used on the image.
height	The height of the image in pixels.
imageType	The type classification of the image. For example: Bilevel: Specifies a monochrome image. ColorSeparation: Specifies a Cyan / Yellow / Magenta / Black (CYMK) image. Grayscale: Specifies a grayscale image. GrayscaleMatte: Specifies a grayscale image with opacity. Palette: Specifies an indexed color (palette) image. PaletteMatte: Specifies an indexed color (palette) image with opacity. TrueColor: Specifies a truecolor image. TrueColorMatte: Specifies a truecolor image with opacity. Some more information can be found here.
numberColours	The number of colours in the image.
numberPages	The number of images within the main image - a feature that is supported only in certain file types, e.g. TIFF.
planes	The number of planes in an image.
quality	An integer value from 1 to 100 that indicates the quality of the image. A lower value indicates a lower image quality and higher compression and a higher value indicates a higher image quality but a lower compression. Only applicable to JPEG and MPEG image formats.
resolution	The resolution of the image in PPI (Pixels per inch).
width	The width of the image in pixels.

The resource and resources virtual columns both return the same type of information as follows:

Returns	Details
identifier	The name of the multimedia file.
mimeType	The media type.
mimeFormat	The media format.
size	The size of the file in bytes.
file	An IO:File object. This provides a read-only handle to a temporary copy of the multimedia file. The temporary copy of the file is discarded when the handle is closed or destroyed. Note If the resource column is specified with a filter, a modifier must also be provided in order for the file handle to be returned, e.g.: 'resources(height @ 200){resource:include}' Modifier options include: resource:include - will add the file handle to the data set returned. resource:only - will replace the data set returned with the file handle.
height	The height of the image in pixels.
width	The width of the image in pixels.

While the Multimedia module virtual columns provide a reasonably fine-grained method for selecting specific multimedia files associated with a multimedia record, in some circumstances it is useful to have even more control over the selection of multimedia files, particularly when specifying the resolutions, resources or supplementary virtual columns.

Filters provide a mechanism to specify particular files associated with a multimedia record based on certain characteristics of the files. Filters consist of three parts; a name, a operator and a value. They are specified in round brackets after a virtual column:

column(nameoperatorvalue)

Multiple values can be specified by separating each filter with a comma:

column(nameoperatorvalue, nameoperatorvalue)

• name

  The filter name specifies the characteristic of the multimedia file to filter on. Unless noted otherwise the meaning of the filter names is as specified in the Multimedia files section.

  The following filter names can be used to filter any multimedia file:

  • fileSize (or size)
  • height
  • identifier
  • index
  • kind
  • mimeFormat (or format)
  • mimeType (or type)
  • width

  The following filter names can be used to filter multimedia image files:

  • bitsPerPixel
  • colourSpace
  • compression
  • imageType
  • md5Checksum (or md5sum)
  • numberColours
  • numberPages
  • planes
  • quality
  • resolution

  The following filter name can be used to filter supplementary multimedia files:

  • usage

    The value of the supplementary attributes usage (SupUsage_tab) column.

• operator

  The operator specifies how the filter value should relate to the multimedia file characteristic specified by the filter name.

  The available values are:

  Value	Name	Details
  ==	Equals	Selects the multimedia files where the characteristic specified by the filter name is the same as the filter value.
  !=	Not equals	Selects the multimedia files where the characteristic specified by the filter name is not the same as the filter value.
  <	Less than	Selects the multimedia files where the characteristic specified by the filter name is less than the filter value. Only applies to numeric values.
  >	Greater than	Selects the multimedia files where the characteristic specified by the filter name is greater than the filter value. Only applies to numeric values.
  <=	Less than or equal to	Selects the multimedia files where the characteristic specified by the filter name is less that or equal to the filter value. Only applies to numeric values.
  >=	Greater than or equal to	Selects the multimedia files where the characteristic specified by the filter name is greater that or equal to the filter value. Only applies to numeric values.
  @	Closest to (also called best fit).	Selects the single multimedia file where the characteristic specified by the filter name is closest to the filter value. Only applies to numeric values.
  ^	Closest to but greater than	Selects the single multimedia file where the characteristic specified by the filter name is closest to but greater than the filter value. Only applies to numeric values.

• value

  The value to filter by. Any value can be used but, obviously, only certain values make sense for each filter. For example, if the fileSize filter is being used then only a numeric value is useful. Similarly, if the mimeType filter is being used then only a text value that corresponds to a valid MIME type is useful.

For example:

1. Select multimedia resolutions with a width greater that 300 pixels:

   resolutions(width > 300)

2. Select the single multimedia resource with a width closest to 600:

   resources(width @ 600)

3. Select the thumbnail resource:

   resources(kind == thumbnail)

4. Specify multiple filters to select the single multimedia resource with a width and height closest to 600:

   resources(width @ 600, height @ 600)

While the IMu API provides a number of ways to select particular multimedia files from a Multimedia record sometimes none of the available files fulfill the required characteristics. Sometimes it is necessary to modify an existing multimedia file to achieve the desired result.

Modifiers provide a mechanism to convert multimedia images returned by the IMu server in a number of ways. The modifications are performed on-the-fly and do not affect the multimedia stored in the Multimedia database; they only apply to the temporary copy of multimedia returned by the IMu API. Modifiers consist of two parts; a name and a value separated by a colon. They are specified in braces (curly brackets) after a resource or resources virtual column:

column{name:value}

Multiple values can be specified by seperating each filter with a comma:

column{name:value, name:value}

Modifiers can also be specified after a filter:

column(…){name:value}

The supported values for name are:

Value	Details
checksum	Include a checksum value with the resource (or resources) virtual column response. While this does not actually apply any modifications to a multimedia file it is useful when you require a checksum for multimedia that has had a modifier applied to it (cf. original multimedia). The allowed value parts are: crc32 Include a CRC32 checksum. md5 Include a MD5 checksum. When the checksum modifier is used, the resource (or resources) virtual column response includes a checksum component.
encoding	Specifies that the actual bytes (available via the file value of the resource or resources virtual column response) of the multimedia should be encoded. By default it is returned as raw binary data. The allowed value parts are: base64 Use the Base64 encoding scheme.
format	Specifies that the multimedia file should be converted to the specified format. If the multimedia is not already in the required format it is reformatted on-the-fly. The IMu server uses ImageMagick to process the image and the range of supported formats is very large. The complete list is available from: http://www.imagemagick.org/script/formats.php. Any of the supported formats can be used as the value part of this modifier.
resource	Specifies that a multimedia file handle should be returned. The allowed value parts are: include only
height	Specifies that the multimedia image file should be converted to the specified height (in pixels). If the Multimedia record contains a resolution with this height, this resolution is returned instead (i.e. no modification is applied). Otherwise the closest matching larger resolution is resized to the requested height on-the-fly. The allowed value parts are any numeric value specifying the height in pixels.
width	Specifies that the multimedia image file should be converted to the specified width (in pixels). If the Multimedia record contains a resolution with this width, this resolution is returned instead (i.e. no modification is applied). Otherwise the closest matching larger resolution is resized to the requested width on-the-fly. The allowed value parts are any numeric value specifying the width in pixels.
aspectratio	Controls whether the image's aspect ratio should be maintained when both a height and a width modifier are specified. If set to no, the aspect ratio is not maintained. by default the aspect ratio is maintained. The allowed value parts are: yes no

Note: Modifiers currently only apply to multimedia images and can only be specified after the Multimedia virtual resource or resources columns.
Only the resource or resources parts of the returned results are affected by modifiers. By design, all other response parts include the information for the original, unmodified multimedia.

For example:

1. Specify a Base64 encoding modifier:

   resource{encoding:base64}

2. Include a CRC32 checksum in the response:

   resource{checksum:crc32}

3. Reformat the multimedia image to the gif format:

   resource{format:gif}

4. Resize the multimedia image to a height of 300 pixels:

   resource{height:300}

5. Resize the multimedia image to a width of 300 pixels:

   resource{width:300}

6. Resize the multimedia image to a height & width of 300 pixels and do not maintain aspect ratio:

   resource{height:300, width:300, aspectratio:no}