Skip to content

Templates

Jump to bottom
Viren070 edited this page Oct 19, 2025 · 9 revisions

This document describes the template system in AIOStreams, allowing users to easily share and apply configurations with a step-by-step process.

Overview

The template system allows users and instance hosters to create, share, and apply pre-defined configurations. This simplifies setup, enables sharing of optimized configurations, and streamlines the user experience. Templates define a set of settings, including API keys, addon configurations, and proxy settings, which can be easily applied.

Template Schema

Templates are defined using the following JSON schema, represented here as a TypeScript type definition using zod:

export const TemplateSchema = z.object({
  metadata: z.object({
    id: z.string().optional().default(crypto.randomUUID()),
    name: z.string().min(1).max(20), // name of the template
    description: z.string().min(1).max(500), // description of the template
    author: z.string().min(1).max(20), // author of the template
    version: z
      .stringFormat('semver', /^[0-9]+\.[0-9]+\.[0-9]+$/)
      .optional()
      .default('1.0.0'),
    category: z.string().min(1).max(20), // category of the template
    services: z.array(ServiceIds).optional(),
    serviceRequired: z.boolean().optional(), // whether a service is required for this template or not.
  }),
  config: UserDataSchema, // config of the template
});

metadata Object

The metadata object contains information about the template:

  • id: A unique identifier for this template. While not required,it is highly recommended to provide this. It allows users to import your template again and overwrite any existing templates of the same ID rather than duplicating their template list. e.g. viren070.my-template-1
  • name: The name of the template (string, 1-20 characters). This is how the template will be shown to the user..
  • description: A description of the template (string, 1-500 characters). Explain what this template is for and what it configures. Some markdown is supported:
    • \n - New lines.
    • **bold text** -> bold text
    • *italics* -> italics
    • [url](https://example.com) -> url
    • * bullet point\n* bullet point 2 ->
      • bulllet point
      • bullet point 2
  • author: The author of the template (string, 1-20 characters).
  • version: Optionally provide a semantic version string to handle changes to your templates. Defaults to 1.0.0
  • category: The category of the template (string, 1-20 characters). Used for organization.
  • services: (Optional) An array of ServiceIds (string) specifying which debrid services are compatible or required. See "Service Handling" below for details.
  • serviceRequired: (Optional) A boolean indicating whether a debrid service is required for this template. See "Service Handling" below for details.

config Object

The config object contains the actual configuration data for the template, matching the UserDataSchema. This includes settings for addons, API keys, proxy configurations, and other user-configurable options.

Template Placeholders

To allow for user-specific input, certain fields within the config can use placeholders. This is particularly useful for API keys and other sensitive information that should not be stored directly in the template.

The following placeholders are supported:

  • <template_placeholder>: This placeholder indicates that the option must be filled in by the user when the template is applied. An input field will be displayed, and the user must provide a value.
  • <optional_template_placeholder>: This placeholder indicates that the option can be filled in by the user. An input field will be displayed, but the user can leave it blank if desired.

These placeholders can be used in any of the following text-based input fields:

  • tmdbApiKey, tmdbAccessToken, rpdbApiKey, tvdbApiKey fields.
  • Addon configuration options (e.g. Nuviostreams' ShowBox API Key)
  • Any proxy configuration value.

Service Handling

The services and serviceRequired metadata fields control how debrid services are handled when the template is applied.

  • services Undefined: If the services array is not present in the metadata, all available debrid services will be shown in the service selection menu. This is the default behavior.
  • serviceRequired Absent/False: If serviceRequired is not present or is set to false, the service selection screen will include a "Skip" button, allowing the user to apply the template without selecting a debrid service.
  • services Defined: If the services array is set to a specific array of ServiceIds, the service selection menu will be limited to only those services.
    • Empty Array []: If the services array is empty, the service selection screen is skipped entirely.
    • Single Service & serviceRequired: true: If the services array contains a single ServiceId and serviceRequired is explicitly set to true, the service selection screen is skipped, and the template will automatically require the user to enter credentials for that specific service.

Template Location and Import

Instance hosters should upload their own templates to the template folder in the data directory. The data directory is ./data by default but will change if you have your DATABASE_URI set to a different folder and are using SQLite.

In the docker container, this will be at /app/data/templates. Templates provided here will show above the "built-in" templates.

Users can then choose from these templates within the AIOStreams interface. Additionally, users can import templates from:

  • A URL pointing to a template file or an array of template objects.
  • A local template file on their device.

Exporting Templates

On the configuration export page, users have the option to export their current configuration as a template file. This allows them to easily share their settings with others or back them up for future use.

Clone this wiki locally