API Documentation

API Documentation / Wiki

The following pages provide an overview about all functions of the API (Application Programming Interface) of the hyper Content & Digital Asset Management Server.
Please note, that you might usually only require few functions for the development of Plugins, template functions like navigation, sitemap and so on. Please read the Template Designers Guide and Programers Guide for a better insight.
The API is primarily used for the implementation of standalone applications that leverage the capabilities of the hyper Content & Digital Asset Management Server. The API is not to be confused with the OpenAPI, which is based on a SOA (Service Oriented Architecture), and is not part of the Free Edition.

For Questions & Answers please visit the Google Group.

hyperCMS API Function Reference

▲ Media API Functions

adjust_brightness

Description
Provides a darker or lighter version of a provided color (Hex-Code).

Syntax
adjust_brightness ($hex, $percent)

Input parameters

$hex ... color as hex-code [string]
$percent ... adjust color by percent from darker -100 to lighter 100 [integer]

Output

adjusted hex-code of the same color / false on error

valid_jpeg

Description
Checks for the existence of the EOI segment header at the end of the file.
Mainly used to verify JPEG images extracted from older Adobe InDesign files.

Syntax
valid_jpeg ($filepath)

Input parameters

$filepath ... path to multimedia file [string]

Output

true / false

ocr_extractcontent

Description
This function extracts the text content of multimedia objects using OCR and returns the text.
It is a helper function for function indexcontent. Do not use function ocr_extractcontent directly since it will not support encrypted media files or media files in cloud storages.

Syntax
ocr_extractcontent ($site, $location, $file, $user, $scan_pages="")

Input parameters

$site ... publication name [string]
$location ... path to multimedia file [string]
$file ... multimedia file name (file to be indexed) [string]
$user ... user name [string]
$scan_pages ... page numbers to be scanned by OCR beginning with 0 for first page and seperated by comma [string] (optional)

global input parameters

$mgmt_config
$mgmt_parser
$mgmt_imagepreview
$hcms_lang
$lang

Output

extracted content as text string / false

indexcontent

Description
This function extracts the text content of multimedia objects and writes the text to the container.
The given charset of the publication (not set by default), container or publication (not set by default) will be used.
The default character set of default.meta.tpl is UTF-8, so all content should be saved in UTF-8.

Syntax
indexcontent ($site, $location, $file, $container="", $container_content="", $user="", $return_content=false)

Input parameters

$site ... publication name [string]
$location ... path to multimedia file [string]
$file ... multimedia file name (file to be indexed) [string]
$container ... container name or ID [string] (optional)
$container_content ... container XML-content [string] (optional)
$user ... user name [string]
$return_content ... return the content without saving it in the system [boolean] (optonal)

global input parameters

$mgmt_config
$mgmt_parser
$mgmt_imagepreview
$mgmt_uncompress
$hcms_ext
$hcms_lang
$lang

Output

true / false

unindexcontent

Description
This function removes media objects from the container

Syntax
unindexcontent ($site, $location, $file, $container, $container_content, $user)

Input parameters

$site ... publication name [string]
$location ... file location [string]
$file ... file name [string]
$container ... multimedia file to index [string]
$container_content ... container name or ID [string]
$user ... container XML-content [string]

global input parameters

$mgmt_config
$mgmt_parser
$hcms_lang
$lang

Output

true / false

reindexcontent

Description
Reindexes all media files of a publication. Optionally only for specific containers.

Syntax
reindexcontent ($site, $container_id_array="")

Input parameters

$site ... publication name [string]
$container_id_array ... container IDs [array] (optional)

global input parameters

$mgmt_config

Output

true / false

base64_to_file

Description
Decodes a base64 encoded string and saves it to as a file.

Syntax
base64_to_file ($base64_string, $location, $file)

Input parameters

$base64_string ... base64 encoded [string]
$location ... path to destination dir [string]
$file ... file name [string]

Output

new file name / false on error

exec_in_background

Description
Executes a shell command in the background

Syntax
exec_in_background ($cmd)

Input parameters

$cmd ... exec command [string

global input parameters

$mgmt_config

Output

createthumbnail_indesign

Description
Creates a thumbnail by extracting the thumbnail from an indesign file and transferes the generated image via remoteclient.
For good results, InDesign Preferences must be set to save preview image at an extra large size.

Syntax
createthumbnail_indesign ($site, $location_source, $location_dest, $file)

Input parameters

$site ... publication name [string]
$location_source ... path to source dir [string]
$location_dest ... path to destination dir [string]
$file ... file name [string]

global input parameters

$mgmt_config
$mgmt_mediametadata
$user

Output

new file name / false on error (saves only thumbnail media file in destination location
only jpeg format is supported as output)

createthumbnail_krita

Description
Creates a thumbnail by extracting the thumbnail from a Krita file and transferes the generated image via remoteclient.

Syntax
createthumbnail_krita ($site, $location_source, $location_dest, $file)

Input parameters

$site ... publication name [string]
$location_source ... path to source dir [string]
$location_dest ... path to destination dir [string]
$file ... file name [string]

global input parameters

$mgmt_config
$mgmt_uncompress
$mgmt_imagepreview
$user

Output

new file name / false on error (saves only thumbnail media file in destination location
only jpeg format is supported as output)

createthumbnail_video

Description
Creates a thumbnail picture of a video frame. Saves only the thumbnail media file in destination location. Only jpeg format is supported as output.
Media files with a valid container identifier in their name will be saved in the cloud storage.

Syntax
createthumbnail_video ($site, $location_source, $location_dest, $file, $frame, $width=0, $height=0, $filename="")

Input parameters

$site ... publication name [string]
$location_source ... path to source dir [string]
$location_dest ... path to destination dir [string]
$file ... file name [string]
$frame ... frame of video in seconds or hh:mm:ss.xxx [integer, time]
$width ... image width in pixel and -1 to keep aspect ratio based on height [integer] (optional)
$height ... image height in pixel and -1 to keep aspect ratio based on width [integer] (optional)
$filename ... individual file name without the file extension of the created image [string] (optional)

global input parameters

$mgmt_config
$mgmt_mediapreview
$mgmt_mediaoptions
$user

Output

new file name / false on error

createimages_video

Description
Creates and saves images of video screen size from a video to a directory.
The media files will be saved in the local repository and not in the cloud storage.

Syntax
createimages_video ($site, $location_source, $location_dest, $file, $name="", $fs=1, $format="jpg", $width=0, $height=0)

Input parameters

$site ... publication name [string]
$location_source ... path to source dir [string]
$location_dest ... path to destination dir [string]
$file ... file name [string]
$name ... name for image files [string] (optional)
$fs ... frames per second to create from the video [number] (optional)
$format ... image format [jpg, png, bmp] (optional)
$width ... image width in pixel and -1 to keep aspect ratio based on height [integer] (optional)
$height ... image height in pixel and -1 to keep aspect ratio based on width [integer] (optional)

global input parameters

$mgmt_config
$mgmt_mediapreview
$mgmt_mediaoptions
$user

Output

true / false on error

createmedia

Description
Creates an new image or video from the original file or creates a thumbnail and transferes the generated image via remoteclient.
Saves original or thumbnail media file in destination location. For the thumbnail only JPEG is supported as output format.

Syntax
createmedia ($site, $location_source, $location_dest, $file, $format="", $type="thumbnail", $force_no_encrypt=false, $setmediainfo=true, $exec_in_background=false)

Input parameters

$site ... publication name [string]
$location_source ... path to source dir [string]
$location_dest ... path to destination dir [string]
$file ... file name [string]
$format ... format (file extension w/o dot) [string] (optional)
$type ... type of image/video/audio file [thumbnail(for thumbnails of images), origthumb(thumbnail made from original video/audio), original(to overwrite original video/audio file), annotation(for annotation images), any other string present in $mgmt_imageoptions/$mgmt_mediaoptions, temp(for temporary files)] (optional)
$force_no_encrypt ... force the file to be not encrypted even if the content of the publication must be encrypted [boolean] (optional)
$setmediainfo ... set media information [boolean] (optional)
$exec_in_background ... create image files in the background [boolean] (optional)

global input parameters

$mgmt_config
$mgmt_imagepreview
$mgmt_mediapreview
$mgmt_mediaoptions
$mgmt_imageoptions
$mgmt_maxsizepreview
$mgmt_mediametadata
$hcms_ext
$user

Output

new file name / false on error

splitmedia

Description
Splits a video or audio file in segments measured in seconds. Used for synchronous Google Cloud Speech Service that only supports max. 1 minute audio files.

Syntax
splitmedia ($site, $location_source, $location_dest, $file, $sec=60, $format="", $force_no_encrypt=false)

Input parameters

$site ... publication name [string]
$location_source ... path to source dir [string]
$location_dest ... path to destination dir [string]
$file ... file name [string]
$sec ... seconds of a segment [integer] (optional)
$format ... target format (file extension w/o dot) of destination file [string] (optional)
$force_no_encrypt ... force the file to be not encrypted even if the content of the publication must be encrypted [boolean] (optional)

global input parameters

$mgmt_config
$mgmt_imagepreview
$mgmt_mediapreview
$mgmt_mediaoptions
$mgmt_imageoptions
$mgmt_maxsizepreview
$mgmt_mediametadata
$hcms_ext
$user

Output

array of new file names / false on error

convertmedia

Description
Converts and creates a new image, video, audio, or document from the source file. This is a wrapper function for createmedia, createimages_video and createdocument.
If the destination media file exists already or is newer than the source file the file name will be returned without conversion.

Syntax
convertmedia ($site, $location_source, $location_dest, $mediafile, $format, $media_config="", $force_no_encrypt=false)

Input parameters

$site ... publication name [string]
$location_source ... path to source dir [string]
$location_dest ... path to destination dir [string]
$mediafile ... file name [string]
$format ... target format (file extension w/o dot) of destination file [string]
$media_config ... media configuration to be used [string] (optional)
$force_no_encrypt ... force the file to be not encrypted even if the content of the publication must be encrypted [boolean] (optional)

global input parameters

$mgmt_config
$mgmt_imagepreview
$mgmt_mediapreview
$mgmt_mediaoptions
$mgmt_imageoptions
$mgmt_maxsizepreview
$mgmt_mediametadata
$mgmt_compress
$hcms_ext

Output

new file name / false on error

convertimage

Description
Converts and creates a new image from original. The new image will be resized and cropped to fit width and height.
This is a wrapper function of function createmedia.

Syntax
convertimage ($site, $file_source, $location_dest, $format="jpg", $colorspace="RGB", $iccprofile="", $width="", $height="", $slug=0, $units="px", $dpi=72, $quality="", $watermark=true)

Input parameters

$site ... publication name [string]
$file_source ... path to source image file [string]
$location_dest ... path to destination dir [string]
$format ... format (file extension w/o dot) of destination file [string] (optional)
$colorspace ... colorspace of new image [CMY, CMYK, Gray, HCL, HCLp, HSB, HSI, HSL, HSV, HWB, Lab, LCHab, LCHuv, LMS, Log, Luv, OHTA, Rec601YCbCr, Rec709YCbCr, RGB, scRGB, sRGB, Transparent, XYZ, YCbCr, YCC, YDbDr, YIQ, YPbPr, YUV] (optional)
$iccprofile ... width in pixel/mm/inch [integer] (optional)
$width ... height in pixel/mm/inch [integer] (optional)
$height ... slug in pixel/mm/inch [integer] (optional)
$slug ... units for width [string]
$units ... height and slug [px, mm, inch] (optional)
$dpi ... dpi [integer] (optional)
$quality ... image quality [1 to 100]
$watermark ... apply watermark [boolean] (optional)

global input parameters

$mgmt_config
$mgmt_imagepreview
$mgmt_mediapreview
$mgmt_mediaoptions
$mgmt_imageoptions
$mgmt_maxsizepreview
$mgmt_mediametadata
$hcms_ext
$user

Output

new file name / false on error

rotateimage

Description
Rotates an image (must be jpg, png or gif) using GD library. not used if ImageMagick is available

Syntax
rotateimage ($site, $filepath, $angle, $imageformat)

Input parameters

$site ... publication name [string]
$filepath ... path to source media file [string]
$angle ... rotation angle [integer]
$imageformat ... destination image format [jpg, png, gif]

global input parameters

$mgmt_config
$user

Output

new image file name / false on error

hex2rgb

Syntax
hex2rgb ($hex)

Input parameters

$hex ... image color as hex-code [string]

Output

RGB-color values as array / false on error

rgb2hex

Syntax
rgb2hex ($red, $green=0, $blue=0)

Input parameters

$red ... image color in RGB [array] or red value [integer]
$green ... green value [integer]
$blue ... blue value [integer]

Output

CMYK color percentage values as array / false on error

readmediaplayer_config

Syntax
readmediaplayer_config ($location, $configfile)

Input parameters

$location ... path to media config file [string]
$configfile ... config file name [string]

global input parameters

$mgmt_config
$mgmt_mediaoptions
$user

Output

config array / false on error

savemediaplayer_config

Syntax
savemediaplayer_config ($location, $configfile, $mediafiles, $width=320, $height=240, $rotation="", $filesize="", $duration="", $videobitrate="", $audiobitrate="", $audiofrequenzy="", $audiochannels="", $video_codec="", $audio_codec="")

Input parameters

$location ... path to media config file [string]
$configfile ... media config file name [string]
$mediafiles ... media file name [array or string]
$width ... width in px [integer] (optional)
$height ... height in px [integer] (optional)
$rotation ... rotation in degree [integer] (optional)
$filesize ... file size in kB [integer] (optional)
$duration ... duration [hh:mmm:ss] (optional)
$videobitrate ... video bitrate in kb/s [string] (optional)
$audiobitrate ... audio bitrate in kb/s [string] (optional)
$audiofrequenzy ... audio frequenzy in Hz [string] (optional)
$audiochannels ... audio channels [mono, stereo] (optional)
$video_codec ... video codec name [string] (optional)
$audio_codec ... audio codec name [string] (optional)

global input parameters

$mgmt_config
$user

Output

true / false on error

createdocument

Description
Creates a new multimedia file of given format at source destination using UNOCONV and saves it as a thumbnail file in the destination location

Syntax
createdocument ($site, $location_source, $location_dest, $file, $format="", $force_no_encrypt=false)

Input parameters

$site ... publication name [string]
$location_source ... path to source location [string]
$location_dest ... path to destination location [string]
$file ... file name [string]
$format ... destination file format (extension w/o dot) [string]
$force_no_encrypt ... force the file to be not encrypted even if the content of the publication must be encrypted [boolean] (optional)

global input parameters

$mgmt_config
$mgmt_docpreview
$mgmt_docoptions
$mgmt_docconvert
$mgmt_maxsizepreview
$hcms_ext
$hcms_lang
$lang
$user

Output

new file name / false on error

unzipfile

Description
Unpacks ZIP file and creates media files in destination location for components or unzips files directly for pages (not recommended due to the security risks by uploading files that can be executed).

Syntax
unzipfile ($site, $zipfilepath, $location, $filename, $cat="comp", $user="", $createmedia_in_background=false, $report=false)

Input parameters

$site ... publication name [string]
$zipfilepath ... path to source zip file [string]
$location ... path to destination location [string]
$filename ... category [page, comp]
$cat ... name of file for extraction [string]
$user ... user name [string]
$createmedia_in_background ... create media files in the background [boolean] (optional)
$report ... output report [boolean] (optional)

global input parameters

$mgmt_config
$mgmt_uncompress
$mgmt_imagepreview
$mgmt_mediapreview
$mgmt_mediaoptions
$hcms_lang
$lang

Output

result array with all object paths / false

clonefolder

Description
Help function for function zipfiles that reads all multimedia files from their multimedia objects and copies them to the same folder structure using the object names.

Syntax
clonefolder ($site, $source, $destination, $user, $activity="")

Input parameters

$site ... publication name [string]
$source ... source location [string]
$destination ... destination location [string]
$user ... user name [string]
$activity ... activity that need to be set for daily stats [download] (optional)

global input parameters

$mgmt_config
$pageaccess
$compaccess
$hiddenfolder
$hcms_linking
$globalpermission
$setlocalpermission

Output

container IDs as array / false

zipfiles_helper

Description
Compresses all files and includes their folder structure in a ZIP file. This function does not support multimedia objects and is only a helper function for native file system operations.

Syntax
zipfiles_helper ($source, $destination, $zipfilename, $remove=false)

Input parameters

$source ... source directory [string]
$destination ... destination directory [string]
$zipfilename ... name of ZIP-file [string]
$remove ... remouse all files from source [boolean] (optional)

global input parameters

$mgmt_config
$mgmt_compress

Output

true/false

zipfiles

Description
Compresses all media files and includes their folder structure in a ZIP file.

Syntax
zipfiles ($site, $multiobject_array, $destination="", $zipfilename="", $user="", $activity="", $flatzip=false)

Input parameters

$site ... publication name [string]
$multiobject_array ... array with path to source files [array]
$destination ... destination location (if this is null then the $location where the zip-file resists will be used) [string]
$zipfilename ... name of ZIP-file [string]
$user ... user name [string]
$activity ... activity that need to be set for daily stats [download] (optional)
$flatzip ... flat hierarchy means no directories [boolean] (optional)

global input parameters

$mgmt_config
$mgmt_compress
$pageaccess
$compaccess
$hiddenfolder
$hcms_linking
$globalpermission
$setlocalpermission
$hcms_lang
$lang

Output

true/false

px2mm

Description
Convert mm to pixel

Syntax
px2mm ($pixel, $dpi=72)

Input parameters

$pixel ... pixel [integer]
$dpi ... dpi [integer] (optional)

Output

pixel / false

px2inch

Description
Convert pixel to inches

Syntax
px2inch ($pixel, $dpi=72)

Input parameters

$pixel ... pixel [integer]
$dpi ... dpi [integer] (optional)

Output

inch / false

inch2px

Description
Convert inches to pixel

Syntax
inch2px ($inch, $dpi=72)

Input parameters

$inch ... pixel [integer]
$dpi ... dpi [integer] (optional)

Output

pixel / false

sec2time

Description
Convert seconds to time format hh:mm:ss.mmm

Syntax
sec2time ($input)

Input parameters

$input ... time in seconds [float]

Output

time in hh:mm:ss.mmm / false

mediasize2frame

Description
Calculates the width and height of a media to fit into a given frame size.

Syntax
mediasize2frame ($mediawidth, $mediaheight, $framewidth="", $frameheight="", $keepmaxsize=true)

Input parameters

$mediawidth ... media width [integer]
$mediaheight ... media height [integer]
$framewidth ... frame width [integer] (optional)
$frameheight ... frame height [integer] (optional)
$keepmaxsize ... keep maximum media size based on original dimensions of media without stretching [boolean] (optional)

Output

width and height as array / false

vtt2array

Description
Converts VTT string to array

Syntax
vtt2array ($vtt)

Input parameters

$vtt ... video text track [string]

Output

array / false

html2pdf

Description
Converts html to pdf using WKHTMLTOPDF and XSERVER. The CSS media print style will be applied.
For full support you might want to install the package provided from WKHTMLTOPDF directly (patched QT).
See the event log in case the function does not create a proper result since you are not using a patched QT version.
See also: https://wkhtmltopdf.org/usage/wkhtmltopdf.txt

Syntax
html2pdf ($source, $dest, $cover="", $toc=false, $page_orientation="Portrait", $page_size="A4", $page_margin=10, $image_dpi=144, $image_quality=95, $smart_shrinking=true, $options="")

Input parameters

$source ... URLs or pathes to html source files [array]
$dest ... path of pdf destination output file [string]
$cover ... cover page html file [string] (optional)
$toc ... create TOC table of contents [boolean] (optional)
$page_orientation ... page orientation [Landscape, Portrait] (optional)
$page_size ... page size like A4 or Letter [string] (optional)
$page_margin ... page margin in mm [integer] (optional)
$image_dpi ... image DPI [integer] (optional)
$image_quality ... image quality 1-100 [integer] (optional)
$smart_shrinking ... use smart shrinking of the content so it can fit in the page [boolean] (optional)
$options ... additional WKHMTLTOPDF options [string] (optional)

global input parameters

$mgmt_config

Output

true / false on error

mergepdf

Description
Merges pdf files into one pdf file. Do NOT USE special characters in file names.
See also: https://www.pdflabs.com/docs/pdftk-man-page/

Syntax
mergepdf ($source, $dest)

Input parameters

$source ... pathes to pdf source files [array]
$dest ... path of pdf destination output file [string]

global input parameters

$mgmt_config

Output

true / false on error

createAIimage

Description
Function to generate images using OpenAI’s DALL-E

Syntax
createAIimage ($site, $inputtext, $size="1024x1024", $model="dall-e-3", $number=1)

Input parameters

$site ... publication name [string]
$inputtext ... image description for the text-to-image AI generator [string]
$size ... image size [WxH] (optional)
$model ... AI model name [string] (optional)
$number ... number of images to generate [integer] (optional)

global input parameters

$mgmt_config

Output

result array / false on error