Introduction

Template Collections are a way to share a collection of images and videos that are used as meme templates with your community. You can upload a Template Collection to your server and share a link to the collection. Other users can add this link in Mematic and access the templates directly from the Memes gallery. If you update the collection, for example by adding new images, these updates will be automatically visible for all users who have added that list.

concept-illustration-hd

If you have any questions about Template Collections, feel free to email us at collections@mematic.net.

(Note: Template Collections are only available on iOS at this time, but will soon also be available on Android.)

Requirements

To create a Template Collection, you need the following:

A webspace where you can host the collection file and images
An iOS device running Mematic to test the collection (Download)
A text editor to edit the collection file
Image editing tools to create thumbnails

For this guide you should know how a webspace works and be familiar with the JSON file format. If you plan to create collections with a large number of templates, some basic programming experience will help to automate the creation of thumbnails and the collection file with scripts.

Overview

The Template Collection API is designed for small collections containing up to 5000 images and videos. All metadata of the collection and every media item, including size information and keywords, is included in a single, static Template Collection File. Mematic downloads that file and performs search locally on the device. This means that your server only needs to serve static files, no additional software is needed. A web space of a free webhoster, a cloud storage or a CDN is sufficient.

Template Collection File Format

A Template Collection File is a JSON formatted text file with the file extension .mtc. Its root object is a Collection object. The file size should not exceed 1 MB. The Template Collection URL is the URL where you have uploaded your Template Collection File.

Collection Resource

The Collection resource is a dictionary that describes a single template of the collection and contains the following data:

Key	Value Type	Description
`version`	String	Required. The version of the collection file format. Must be `1.0`
`identifier`	String	Required. The identifier of the collection. 8-50 characters. Allowed characters are `a-z`, `A-Z`,`0-9`, `-`, `.`, `_`, `#`.
`name`	String	Required. The name of the collection. 3-50 characters.
`author`	String	Required. The author of the collection. 3-50 characters.
`contactEmail`	String	Optional. A contact email address of the collection author. Either this property or `contactUrl` must be provided.
`contactUrl`	String	Optional. A contact URL of the collection author. Must be a valid URL that starts with `https://`. Either this property or `contactEmail` must be provided.
`contentType`	String	Optional. If set, it must be `memes`.
`baseUrl`	String	Required. A URL pointing to the directory that contains all media files. Must start with `https://`.
`templates`	array of `Template` objects	Required. Metadata of the images and videos contained in the collection. Up to 5000 objects are allowed.

Identifier

The identifier will not be visible for the user. It is used by Mematic for various purposes, for example to save favorites. No two lists with the same identifier can be added to Mematic. If you change the identifier of a published collection an error will be displayed for users that have already added the collection to Mematic. If you re-publish the collection with another identifier, this will likely cause unexpected behavior and cause confusion for users.

As the identifier cannot be updated, choose something that permanently and uniquely describes your collection. Good examples are strings that contain the domain of your website (stampcollectors.example.com), the subreddit that you moderate (r/memes#retro-comics), or your unique user name (master-otaku.photography).

Name and contact information

The name and author strings are read once when the user adds the collection to Mematic. If you change these properties, users who already added the collection will not see this change. This is to avoid confusing users who rely on this information to navigate their template collections and understand the source of the collections.

A collection must contain either contactEmail or contactUrl. The values are displayed in Mematic in the collection’s details as a way to contact the collection provider when users manage their lists or wish to report content. If both properties are provided, both are displayed. You can update these properties.

Content type

If contentType is set to memes, the templates in the collection are by default merged with the standard meme collection that is provided with Mematic. This is useful if you aim to provide a collection that extends the Mematic meme collection.

If you omit contentType, the template collection is by default listed as a separate source.

The user can override this setting in Mematic after adding the collection.

Base URL

The baseUrl must be a valid URL that starts with https://. The baseUrl is used to resolve the URLs of the media files of the collection. Note that the Template Collection File itself can be hosted on a different server than the media files.

The provided name, contact information and baseUrl must not contain the word “Mematic”. Do not choose values that suggest that the collection is an official collection of Mematic or that it’s endorsed by the developers of Mematic.

Template Resource

The Template resource is a dictionary that describes a single template of the collection and contains the following data:

Key	Value Type	Description
`id`	String	Required. The identifier of the template. 3-50 characters. Allowed characters are `a-z`, `A-Z`, `0-9`, `-`.
`name`	String	Optional. The name of the template. 3-50 characters. Displayed in the app.
`keywords`	String	Optional. A string containing a comma separated list of keywords. Up to 150 characters.
`size`	array of Integers	Required. An array containing the width and height of the “full size” original media item in pixels.
`layout`	array of String	Optional. An array containing hints for recommended meme layouts. Possible values are `free` and `billboard`.
`originalUrl`	String	Optional. A URL relative to `baseUrl`, pointing to the original file of the template.
`thumbnailUrl`	String	Optional. A URL relative to `baseUrl`, pointing to the thumbnail file of the template.
`mediaFormat`	String	Optional. A key that indicates the media format of the item. Possible values are `jpg` and `mp4`. Default: `jpg`

Each template refers to either an image or a video that can be used as a project background or meme template in Mematic. The name property is displayed in the app. Both name and keywords are used to create an index in the app that allows the users to search the collection. Keywords that are already in name don’t need to be repeated in keywords. Note that the contents of id will not be indexed.

Media URLs

Mematic creates the download URLs of a template’s media and its thumbnail as follows:

If you have provided an originalUrl or thumbnailUrl for the template, Mematic will resolve these as URLs relative to baseUrl. originalUrl and thumbnailUrl cannot be absolute URLs. If you have not provided originalUrl or thumbnailUrl, Mematic will create URLs as follows:

`mediaFormat`	Thumbnail URL	Original URL
`jpg`	`<baseUrl>thumbnails/<id>.jpg`	`<baseUrl>original/<id>.jpg`
`mp4`	`<baseUrl>thumbnails/<id>.gif`	`<baseUrl>original/<id>.mp4`

You must create the required directories on your server and upload the media files of your collection into these directories so that the images, videos and their thumbnails can be downloaded from the resolved URLs.

Media requirements

Extreme aspect ratios of media are not allowed: Media must not be wider than 3:1 or narrower than 1:3. Thumbnails must have the same aspect ratio as the original media.

Requirements for images:

Images and their thumbnails must be provided as JPEG files
The size of an image must not be larger than 4096px or smaller than 10px in either dimension.
The file size of an image should be less than 1 MB.
The width of a thumbnail should be 400px, it must not be larger than that.
The file size of an image thumbnail should be less than 30 KB.

Requirements for videos:

Videos must be provided as MPEG4 files
The size of a video must be up to 1920 x 1080 pixels or up to 1080 x 1920 pixels, and not smaller than 10 x 10 pixels.
The file size of a video should be smaller than 3 MB and must be smaller than 8 MB
Video thumbnails must be provided as GIF files
The width of a video thumbnail should be 220px, it must not be larger than 400px
The file size of a video thumbnail should be less than 250 KB.

Keep in mind that if you’re creating a gallery with meme templates, resolutions smaller than these limits are likely preferrable. Smaller images and videos ensure faster downloads, require less data and Mematic will probably have a better performance during editing. For images used as meme templates, aim for sizes up to 1200px in either dimension and file sizes of less than 200 KB.

Distribution

To make your Template Collection available to other users, share the Template Collection URL. Users can copy that URL and paste it in Mematic when adding a new Template Collection.

You can also create a URL using the mematic:// scheme. This will make it much easier for users to add your collection to Mematic: If they open such a link on a device where Mematic is installed, Mematic will automatically open and display a UI to add the collection.

To create such a URL, take your Template Collection URL and replace https:// with mematic://templateCollection/add/. For example:

https://www.example.com/assets/memeCollection.mtc

becomes

mematic://templateCollection/add/www.example.com/assets/memeCollection.mtc

Mematic Behavior

Here are some behaviors of Mematic that are useful to know when you’re creating your collections:

Mematic caches downloaded media files locally for a long time and does not start a new request if a media file is present in the local cache.
Mematic caches downloaded Template Collection Files locally, but checks for new versions once per day.
Mematic does not follow redirects, except for 304.
Content exceeding the hard limits of media dimensions and file sizes might not be downloaded or displayed in Mematic.
Thumbnails may be cropped while browsing a collection.

Testing

To test a Template Collection, you can enable a special test mode for Mematic. To enable the test mode, open the Settings app, scroll down and select “Mematic” and select “Template Collections Test Mode”. This test mode is only available on Mematic for iOS.

settings

While the test mode is enabled, you will see additional tools, detailed error messages and an error log to debug your template collections.

Example Collection

An example Template Collection is hosted at https://www.mematic.net/template-collection/example.mtc (Mematic link: mematic://templateCollection/add/www.mematic.net/template-collection/example.mtc)

The contents of the Template Collection File is the following:

{
  "version": "1.0",
  "identifier": "net.mematic.exampleCollection",
  "name": "Example Template Collection",
  "author": "Frog Fan",
  "contactUrl": "https://mematic.net",
  "contactEmail": "collections@mematic.net",
  "baseUrl": "https://template-collections.b-cdn.net/media/",
  "contentType": "memes",
  "templates": [
    {"id":"smiling-stock-photo-guy","keywords":"smiling man with a coffee, stock photo","size":[1280,960]},
    {"id":"the-frog-prince","keywords":"butterfly sitting on a","layout":["free","billboard"],"name":"The Frog Prince","size":[1280,853],"thumbnailUrl":"photos/2018/thumbs/the-frog-prince.jpg","originalUrl":"photos/2018/the-frog-prince.jpg"},
    {"id":"confused-gorilla","name":"Confused Gorilla","size":[1280,1032]},
    {"id":"nervous-frog","mediaFormat":"mp4","name":"Nervous Frog","size":[1280,720]},
    {"id":"serious-scientist","keywords":"using a microscope","layout":["billboard"],"name":"Serious Scientist","size":[1280,853]},
  ]
}

The two media URLs for the first image are

https://template-collections.b-cdn.net/media/original/smiling-stock-photo-guy.jpg

and

https://template-collections.b-cdn.net/media/thumbnails/smiling-stock-photo-guy.jpg

The two media URLs for the second image are

https://template-collections.b-cdn.net/media/photos/2018/the-frog-prince.jpg

and

https://template-collections.b-cdn.net/media/photos/2018/thumbs/the-frog-prince.jpg

Notes

You are fully responsible for the content that you host in your Template Collections.
The availability of Template Collection features in Mematic is not guaranteed.
Template Collections that are published with the intent to exploit possible bugs or otherwise impair the functionality or operability of Mematic or try to deceive users of the collection can be blacklisted.

_{Last updated on 2023-02-03}

Mematic Template Collections

Documentation of the Mematic Template Collection format