Media Server

Introduction

The "media" within the ComUnity Platform's Media Services alludes to the diverse range of content types that the platform can handle, enriching the architecture of digital solutions. The Media Services component of the ComUnity Platform offers a robust layer that efficiently processes requests for every content type it supports. This encompasses two main categories: structured and unstructured data.

Structured Data Handling

Structured data transactions leverage the OData protocol, presenting a dual interface comprising an API for data manipulation and a URL-based query domain-specific language (DSL) for information retrieval. This approach ensures:

• Data Parsing: Interprets OData requests to determine the appropriate data entities, supporting authorisation and adherence to data governance policies.

• Value-Added Processing: Prior to data relay to the business logic layer, the system performs essential processing for optimisation.

• Error Handling: Enhances the developer experience by appending diagnostic information to errors for quicker resolution.

Unstructured Data Management

Unstructured data, particularly a wide array of file types, is handled with robust capabilities:

• Azure Blob Storage Integration: Seamlessly uploads and downloads large files (up to 270 GB), featuring functionalities such as de-duplication, download resumption, and cache management.

• HTTP Feature Utilisation: Employs partial GET requests, enabling browsers to manage video playback efficiently when accessing large video files hosted on the platform.

Specialised Media Processing

The platform excels in media adaptation and optimisation through:

• Image Transformation Pipeline: Utilises a declarative approach for dynamic image processing, which adapts content according to device capabilities to optimise bandwidth and processing requirements.

• Caching Mechanism: Improves performance by caching image transformations, minimising CPU usage on subsequent requests.

Iconography Support

Delivering a comprehensive icon set handling, the server:

• SVG API Utilisation: Offers access to standard icon repositories, including Font Awesome, Noun Project, and Material Design, complete with on-the-fly rasterisation connected to the image transformation pipeline for efficient icon generation.

By default the ComUnity Developer Toolkit Media Server supports anonymous public read access to storage resources, to increase the security of your applications you may opt to use the managed media server as it only allows permission based and time-bound access to storage resources.

// Supported file formats:
Extension -> MIME type
		.jar 		application/java-archive
		.json 		application/json
		.doc 		application/msword
		.bin 		application/octet-stream
		.pdf 		application/pdf
		.crl 		application/pkix-crl
		.eps 		application/postscript
		.apk 		application/vnd.android.package-archive
		.xls 		application/vnd.ms-excel
		.xlsm 		application/vnd.ms-excel.sheet.macroEnabled.12
		.ppt 		application/vnd.ms-powerpoint
		.pptm 		application/vnd.ms-powerpoint.presentation.macroEnabled.12
		.docm 		application/vnd.ms-word.document.macroEnabled.12
		.xps 		application/vnd.ms-xpsdocument
		.xlsx 		application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
		.docx 		application/vnd.openxmlformats-officedocument.wordprocessingml.document
		.pptx 		application/vnd.openxmlformats-officedocument.presentationml.presentation
		.cod 		application/vnd.rim.cod
		.rm 		application/vnd.rn-realmedia
		.wasm 		application/wasm
		.xhtml 		application/xhtml+xml
		.z 			application/x-compress
		.manifest 	application/x-ms-manifest
		.gz 		application/x-gzip
		.swf 		application/x-shockwave-flash
		.tar 		application/x-tar
		.zip 		application/x-zip-compressed
		.midi 		audio/mid
		.mp3 		audio/mpeg
		.oga 		audio/ogg
		.wav 		audio/wav
		.wma 		audio/x-ms-wma
		.bmp 		image/bmp
		.gif 		image/gif
		.jpg 		image/jpeg
		.png 		image/png
		.svg 		image/svg+xml
		.tiff 		image/tiff
		.ico 		image/x-icon
		.pnm 		image/x-portable-anymap
		.wbmp 		image/vnd.wap.wbmp
		.plist 		application/x-plist
		.mht 		message/rfc822
		.css 		text/css
		.csv 		text/csv
		.html 		text/html
		.js 		text/javascript
		.txt 		text/plain
		.jad 		text/vnd.sun.j2me.app-descriptor
		.xml 		text/xml
		.vcf 		text/x-vcard
		.3gp 		video/3gpp
		.avi 		video/avi
		.mov 		video/quicktime
		.mp4 		video/mp4
		.mpg 		video/mpeg
		.ogg 		video/ogg
		.webm 		video/webm
		.flv 		video/x-flv
		.asf 		video/x-ms-asf
		.wmv 		video/x-ms-wmv
		.movie 		video/x-sgi-movie
		.msg 		application/vnd.ms-outlook

Managing file uploads

SHA File Naming

All files uploaded to the media follow a SHA’s standard file naming convention:

Although use of the SHA File Naming convection prevents duplicate file uploads, its main disadvantage is that uploading an existing file/s are overwritten.

Image file types

SHA_of_file.red.green.blue.alpha.width.height.file_extension 
e.g.
081b278349bb8499788bca8427f11063c73a666a66a8422840311e3397de5ad5.186.188.189.0.300.300.png

Other file types

SHA_of_file.file_extension
e.g.
0aa941b04274ae04dc5a9bd214f7d5214f36e6de.txt 
4dac5a4344f76fdcc496af643cfb094de5fcc6743f8e125c1e4c4415d5115a0c.xml 

The Filenames Data Service maintains a mapping of the original file name (or friendly name) to the SHA name.

Upload a single file

// Example of uploading an image to the Breede app media server using POSTMAN
POST https://breede.qa.comunity.me/u/web_main_menu.png HTTP/1.1
		Content-Type: application/octet-stream
		User-Agent: PostmanRuntime/7.32.3
		Accept: */*
		Cache-Control: no-cache
		Postman-Token: dc9d1faa-56e6-4c11-b7f6-46a4d532fcc7
		Host: breede.qa.comunity.me
		Accept-Encoding: gzip, deflate, br
		Connection: keep-alive
		Content-Length: 944662
		<binary file content>
		
		HTTP/1.1 201 Created
		Server: Microsoft-HTTPAPI/2.0
		access-control-allow-headers: Authorization,Content-Type,Cache-Control,X-Requested-With,X-XSRF-TOKEN,If-None-Match,X-Original-Id
		access-control-allow-origin: *
		access-control-allow-methods: GET,POST,PUT,DELETE,PATCH,OPTIONS
		Location: /u/d/e04507068cd8da2e65eb3cbd7968265e876f94daaae38086ab08c9ce34293041.202.194.189.0.1852.1135.png
		ETag: "f062bd36e355276449b5e0f88ba9a82bae9b694cf1b208b5e84defff0acf1830"
		Date: Fri, 07 Jul 2023 10:55:03 GMT
		Content-Length: 92
		e04507068cd8da2e65eb3cbd7968265e876f94daaae38086ab08c9ce34293041.202.194.189.0.1852.1135.png

Retrieve files

The format of the URL used to retrieve storage resources from a public Media server:

<<Base URL>>/u/<<args>>

Notes:

• Base URL: this specifies the base url of your project, during development its https://toolkitv3.comunity.me

• u : this segment of the URL denotes the Media Server, it is required.

• args represent various arguments or parameters which are used to define your search.

Argument	Type	URL Definition
d	Direct	/u/d/<<SHA File Name>>
f	Friendly	/u/f/<<Friendly File Name>>
icon	Icon	/u/icon/<<RRGGBB>>/<<size>>/<<opacity>>/<<icon_image>>
g	Graphics Magick	/u/g/<<SHA File Name>>/<<modifier>>

Image manipulation

When fetching images from the Media Server you can append optional arguments to the URL string which allow you to manipulate your images. These modifiers used to manipulate images are derived from Graphics Magick.

The table below describes the image modifiers supported in the Media Server:

The descriptions in the table below were generated using Chat GPT.

Modifier	Name	Description
$autoOrient	Auto orient	This modifier is used to automatically adjust the orientation of an image based on its embedded EXIF data. When a photo is taken, the camera records its orientation in the image's metadata. However, some image editors or viewers may not properly handle this information, causing the image to appear rotated incorrectly. The $autoOrient modifier automatically reads the orientation data and rotates the image accordingly. This can be especially useful when dealing with images uploaded from mobile devices or cameras with rotating sensors
$blur/ <<radius>>/<<sigma>>	Blur	This modifier applies a Gaussian blur to the image, which can be used to reduce noise or soften details. The <<radius>> parameter specifies the radius of the blur kernel, and the <<sigma>> parameter controls the standard deviation of the Gaussian distribution. A larger <<radius>> value will result in a more blurry image, while a larger <<sigma>> value will result in a smoother transition between pixels. The $blur modifier can be used in combination with other modifiers to achieve various effects, such as creating a shallow depth of field or simulating motion blur.
$border/<<width>>/<<height>>/<<colour>>	Border	This modifier adds a border of a specified width and height around the image, with a specified color. The <<width>> and <<height>> parameters specify the size of the border, and the <<colour>> parameter specifies the colour of the border. The <<colour>> parameter can be specified using a variety of formats, including hexadecimal values (e.g. #FF0000), RGB values (e.g. rgb(255,0,0)), or color names (e.g. red). The $border modifier can be used to add visual separation between an image and its surroundings or to create a frame around an image.
$charcoal/<< factor>>	Charcoal	The $charcoal/<<factor>> modifier applies a charcoal-like effect to the image, simulating the appearance of a charcoal sketch. The <<factor>> parameter controls the intensity of the effect, with higher values producing more pronounced results. This effect works by simulating the appearance of charcoal on paper, emphasising the edges and contours of the image while reducing the amount of detail and texture. This can be useful for creating artistic or stylized versions of photographs or illustrations. The $charcoal modifier can be combined with other modifiers, such as resizing or cropping, to achieve various effects.
$colorize/<<red>>/ <<green>>/<<blue>>	Colorize	This modifier applies a colour tint to the image, changing the colour balance of the image by blending the original colours with the specified tint. The <<red>>, <<green>>, and <<blue>> parameters specify the intensity of the red, green, and blue colour channels respectively, ranging from 0 to 255. Setting all three values to 0 will result in a grayscale image, while setting them all to 255 will result in a fully saturated tint. The $colorize modifier can be used to add a coloured effect to an image, such as a sepia tone or a blueish tint. This modifier can also be used in combination with other modifiers, such as resizing or cropping, to achieve various effects.
$contrast/<<+-multiplier>>	Contrast	This modifier modifier adjusts the contrast of the image by multiplying the pixel values by a specified factor. The <<+-multiplier>> parameter can be a positive or negative floating point value, with values greater than 1 increasing the contrast and values between 0 and 1 decreasing the contrast. Negative values will invert the image, effectively swapping the light and dark areas. This modifier can be used to adjust the overall brightness and contrast of an image, bringing out details or emphasizing certain areas. It can also be used in combination with other modifiers, such as resizing or cropping, to achieve various effects.
$crop/<<x>>/<<y>>	Crop	The $crop/<<x>>/<<y>> modifier crops the image to a specified size by removing portions of the image outside the specified region. The <<x>> and <<y>> parameters specify the dimensions of the cropped image in pixels, with <<x>> representing the width and <<y>> representing the height. The $crop modifier can be used to remove unwanted portions of an image or to create a thumbnail of a larger image. When used in combination with other modifiers, such as resizing or rotation, the $crop modifier can be used to achieve various effects. It is also possible to specify the position of the crop area using additional parameters, such as $crop/<<x>>/<<y>>/<<width>>/<<height>>, where <<width>> and <<height>> represent the dimensions of the crop area and <<x>> and <<y>> represent the position of the top-left corner of the crop area.
$drawText/<<x>>/<<y>>/<<text>>/<<colour>>/<<fontSize>>	Draw Text	This modifier adds text to the image at a specified position. The <<x>> and <<y>> parameters specify the coordinates of the top-left corner of the text box in pixels. The <<text>> parameter specifies the text to be added to the image. The <<colour>> parameter specifies the color of the text, which can be specified using a variety of formats, including hexadecimal values, RGB values, or color names. The <<fontSize>> parameter specifies the size of the text in points. The $drawText modifier can be used to add titles, captions, watermarks, or other textual elements to images. The position of the text can be adjusted using different values for <<x>> and <<y>>, and the appearance of the text can be customized by changing the values of the <<colour>> and <<fontSize>> parameters. The $drawText modifier also supports additional parameters for adjusting the font, style, and alignment of the text.
$enhance	Enhance	The $enhance modifier applies an image enhancement algorithm to the image, improving the overall clarity and detail of the image. This modifier works by analyzing the image and adjusting the brightness, contrast, and sharpness of the image to bring out more detail and reduce noise. The $enhance modifier can be used to improve the quality of photographs or other images that may be slightly blurry or lacking in detail. It can also be used in combination with other modifiers, such as resizing or cropping, to achieve various effects.
$equalize	Equalize	The $equalize modifier applies histogram equalization to the image, adjusting the distribution of pixel values to improve the contrast and visibility of details in the image. This modifier works by mapping the pixel values of the image to a new set of values that are more evenly distributed across the available range. The result is an image with improved contrast and brightness, with details that may have been difficult to discern in the original image now more visible. The $equalize modifier can be used to improve the visibility and clarity of images that may have been poorly exposed or have uneven lighting. It can also be used in combination with other modifiers, such as resizing or cropping, to achieve various effects. However, it should be noted that the application of this modifier can sometimes lead to an exaggerated or unnatural appearance in some images, and may not always be suitable for every use case.
$flatten	Flatten	The $flatten modifier merges all layers of the image into a single layer, resulting in a flattened image. This modifier is useful when working with images that have multiple layers, such as those that have been created in image editing software, or when combining multiple images into a single image. When multiple layers are present in an image, each layer can contain different visual elements, such as text, graphics, or effects. The $flatten modifier removes these layers and combines all the visual elements into a single layer, resulting in a simplified image that can be used for various purposes. It should be noted that applying the $flatten modifier is a destructive operation, as it permanently removes the separate layers from the image. It is therefore important to create a backup copy of the original image before using this modifier.
$flip	Flip Vertically	The $flip modifier flips the image horizontally along the vertical axis, effectively creating a mirror image of the original image. This modifier is useful when working with images that need to be reversed or mirrored, such as when creating reflections or simulating a flipped object. When applied, the $flip modifier changes the orientation of the image, effectively flipping it from left to right. This can be used to create a symmetrical effect or to correct the orientation of an image that may have been scanned or captured in an inverted or mirrored state. It is important to note that the $flip modifier is a non-destructive operation, meaning that the original image is not modified in any way. Instead, a new image is created with the flipped orientation.
$flop	Flip Horizontally	The $flop modifier flips the image vertically along the horizontal axis, effectively creating an upside-down version of the original image. This modifier is useful when working with images that need to be reversed or mirrored, such as when creating reflections or simulating a flipped object. When applied, the $flop modifier changes the orientation of the image, effectively flipping it from top to bottom. This can be used to create a symmetrical effect or to correct the orientation of an image that may have been scanned or captured in an inverted or mirrored state. It is important to note that the $flop modifier is a non-destructive operation, meaning that the original image is not modified in any way. Instead, a new image is created with the flipped orientation.
$normalize	Normalise	The $normalize modifier applies a normalization algorithm to the image, adjusting the contrast and brightness of the image so that the full range of pixel values is utilized. This modifier is useful for images that have uneven lighting or contrast, or images that have been poorly exposed. When applied, the $normalize modifier analyzes the distribution of pixel values in the image and adjusts them so that the darkest pixels are set to black, and the brightest pixels are set to white, with all other pixel values adjusted proportionally in between. This results in an image with improved contrast and brightness, with details that may have been difficult to discern in the original image now more visible. The $normalize modifier can be used to improve the visibility and clarity of images that may have been poorly exposed or have uneven lighting. It can also be used in combination with other modifiers, such as resizing or cropping, to achieve various effects.
$oil/<<radius>>	Oil painting	The $oil modifier applies an oil painting effect to the image, simulating the appearance of an oil painting by applying a brushstroke-like texture to the image. This modifier is useful for adding a creative effect to photographs or other images. When applied, the $oil modifier analyzes the image and applies a filter that simulates the appearance of brushstrokes. The level of detail in the brushstrokes is controlled by the radius parameter, with larger values resulting in a more pronounced effect. It is important to note that the $oil modifier is a non-destructive operation, meaning that the original image is not modified in any way. Instead, a new image is created with the oil painting effect applied. Additionally, it should be noted that the $oil modifier may not be suitable for all types of images, and may produce better results on certain types of images, such as landscapes or portraits.
$resize/<<width>>/<<height>>/ <<options>>	Resize	m – maintain aspect ratio but width and height are minimum ! – exact size p – size in percentage a – maximum area in pixels of an image g – change dimensions only if width or height exceeds s – resizes only if both dimension are less
$rotate/<<colour>>/<<degrees>>	Rotate	The $rotate modifier rotates the image by a specified number of degrees, with an optional background color for the empty space created by the rotation. This modifier is useful for adjusting the orientation of images that may have been taken at an angle, or for creating special effects with rotated images. When applied, the $rotate modifier rotates the image by the specified number of degrees, either clockwise or counterclockwise. The background color parameter specifies the color to use for the empty space created by the rotation, if any. If no background color is specified, the empty space is filled with transparency. The $rotate modifier can be used to adjust the orientation of images that may have been taken at an angle, or to create special effects with rotated images. For example, rotating an image by 45 degrees and applying other modifiers, such as resizing or cropping, can create a unique and interesting visual effect. It is important to note that rotating an image can result in loss of quality or detail, particularly if the rotation angle is large. It is therefore recommended to use the $rotate modifier judiciously and to carefully consider the desired output before applying it.
$sepia	Sepia	The $sepia modifier applies a sepia tone effect to the image, giving it an aged, vintage look. This modifier is useful for adding a nostalgic or artistic effect to photographs or other images. When applied, the $sepia modifier converts the image to a sepia tone by reducing the saturation of the image and applying a brownish-yellow color cast. The amount of sepia tone applied can be adjusted by changing the intensity of the effect.
$thumb/<<size>>	Thumbnail	The $thumb modifier creates a thumbnail image of the original image with a specified maximum size. This modifier is useful for creating smaller versions of images for use on websites or in documents.
$type/<<type>>	Type	<<type>> - Bilevel Grayscale (default) Palette PaletteMatte TrueColor TrueColorMatte ColorSeparation ColorSeparationMatte Optimize

Option	Details
colour	Named colour, e.g. red 0xRGB, hex numbers 0xRRGGBB, 8 bits each 0xRRGGBBAA, 8 bits each
gravity	NorthWest, North, NorthEast, West, Center, East, SouthWest, South, or SouthEast
options	m – maintain aspect ratio but width and height are minimum ! – exact size p – size in percentage a – maximum area in pixels of an image g – change dimensions only if width or height exceeds s – resizes only if both dimension are less
type	Bilevel Grayscale (default) Palette PaletteMatte TrueColor TrueColorMatte ColorSeparation ColorSeparationMatte Optimize