AIOStreams Custom Formatter - Complete Syntax and Configuration Reference (2026)

28 min readAdvanced Reference

This page is focused on formatter behavior only. For end-to-end addon setup (services, filters, sorting, install), use AIOStreams: Complete Setup and Configuration Guide.

Formatter Pipeline: How It Works

When AIOStreams builds a stream row, formatter execution happens after stream aggregation and filtering:

1. Stream data is normalized into objects (stream, service, addon, config, debug).
2. Your format string is parsed token-by-token.
3. Variable tokens are resolved.
4. Modifiers are applied left-to-right.
5. Conditional blocks are evaluated.
6. The final name and description strings are returned to Stremio.

Key practical effect:

• A clean formatter can make a large result list instantly readable.
• A noisy formatter can hide the quality/safety signals your filters already worked to produce.

Configure Menu Basics

In AIOStreams, formatter configuration has two major modes:

• Predefined format template
• Custom format template

Recommended sequence:

1. Start from a predefined format.
2. Add one custom change at a time.
3. Verify output in the preview panel before saving.

💡 Tip

Use short labels first, then add detail in the description line. On TV devices, long first-line labels reduce scannability.

Template Syntax

1) Variable Access

Base token format:

{path.to.value}

Examples:

• {stream.resolution}
• {stream.quality}
• {service.name}
• {addon.name}

2) Modifier Chains

Modifiers are appended with ~:

{stream.resolution~lower}

Multiple modifiers run in order:

{stream.title~lower~replace( ,.)~upper}

3) Conditional Output Blocks

Block form:

{variable~condition[trueOutput||falseOutput]}

Example:

{stream.cached~istrue[CACHED||UNCACHED]}

4) Multi-Condition Expressions

You can combine checks:

• and
• or
• xor

Example:

{stream.cached~istrue and stream.resolution>=2160[4K CACHED||STANDARD]}

5) Tools (Formatting Helpers)

Tool tokens are available for string layout control. Commonly used:

• newLine
• removeLine

Use these carefully because Stremio clients render line breaks differently by device and view.

Variable Groups

AIOStreams exposes structured data contexts. The exact keys can evolve by version, but these groups are stable:

• stream.*: stream-level values (quality, size, language, tags, cache flags, message fields)
• service.*: service metadata (service name/type/provider context)
• addon.*: originating addon metadata
• config.*: selected config flags
• debug.*: diagnostic fields (when available)

Most real templates rely primarily on stream.*, with occasional service.* and addon.* fallback markers.

Modifiers: Full Matrix

String Modifiers

• upper: uppercase text
• lower: lowercase text
• title: title case text
• replace(old,new): string replacement
• truncate(n): cut to max length n
• length: string length
• reverse: reverse character order

Number Modifiers

• bytes: human-readable size (binary/IEC style)
• bytes2: alternative byte display style
• rbytes: reverse conversion formatting variant
• rbytes2: alternative reverse-byte style
• time: human-readable time unit display
• hex: hexadecimal conversion
• octal: octal conversion
• binary: binary conversion

Array Modifiers

• join(separator): join array values into one string
• length: number of elements
• first: first element
• last: last element

Boolean / Existence Modifiers

• istrue
• isfalse
• exists

Comparison Modifiers

• =X
• >=X
• >X
• <=X
• <X

Text Match Modifiers

• $X: starts with
• ^X: ends with
• ~X: contains

Conditional Patterns (Production)

1) Cache Badge

{stream.cached~istrue[CACHED||UNCACHED]}

Use case:

• Always display cache state first for fast selection.

2) 4K Priority Marker

{stream.resolution>=2160[4K||HD/SD]}

Use case:

• Quick split when mixed qualities appear.

3) Language Fallback

{stream.language~exists[{stream.language}||LANG ?]}

Use case:

• Avoid empty language fields in output.

4) Conditional Detail Line

{stream.seeders>0[{stream.seeders} seeders||P2P stats unavailable]}

Use case:

• Show extra diagnostics only when signal exists.

Name vs Description Design Rules

Recommended layout:

• Name line: short, decision-critical info.
• Description line: diagnostics and secondary details.

Example split:

Name:

{stream.resolution} {stream.quality} {stream.cached~istrue[C||U]}

Description:

{service.name} | {addon.name} | {stream.size~bytes}

This keeps remote-navigation fast while preserving context.

Template Blueprints You Can Reuse

Blueprint A: Daily Driver

Name:

{stream.resolution} {stream.quality} {stream.cached~istrue[CACHED||UNCACHED]}

Description:

{stream.size~bytes} | {service.name} | {stream.language}

Why:

• High scan speed, low noise, good for TV remotes.

Blueprint B: Quality-Focused

Name:

{stream.resolution} {stream.visualTag} {stream.audioTag} {stream.cached~istrue[C||U]}

Description:

{stream.size~bytes} | {stream.encode} | {service.name} | {addon.name}

Why:

• Adds HDR/audio clarity for home theater setups.

Blueprint C: Troubleshooting

Name:

{stream.resolution} {stream.quality} {stream.cached~istrue[C||U]}

Description:

{service.name} | {addon.name} | {stream.message~exists[{stream.message}||OK]} | {stream.seeders}

Why:

• Helps identify bad source behavior and filtering mistakes.

Common Failure Modes and Fixes

Empty Output Fields

Symptom:

• Label contains repeated separators like || or trailing |.

Fix:

• Wrap uncertain fields with exists conditions and fallback text.

Overlong Labels

Symptom:

• Text clipping on Android TV / Fire TV.

Fix:

• Move diagnostics to description.
• Add truncate(n) on unstable long fields.

Incorrect Numeric Display

Symptom:

• Raw byte counts or unreadable integer values.

Fix:

• Add size/time modifiers (bytes, time) where relevant.

Preview Looks Fine, Device Looks Different

Symptom:

• Line breaks or spacing differ across clients.

Fix:

• Keep format robust without relying heavily on multiline rendering.

Formatter and Filtering Strategy

Formatter does not replace filtering.

Best practice stack:

1. Filters remove bad candidates.
2. Sorting ranks remaining candidates.
3. Formatter communicates rank reasons clearly.

If you use formatter tricks to “hide” poor results, selection quality still degrades.

Version Drift Notes

Formatter syntax and available variables can change between releases/instances.

When migrating:

1. Re-open preview and test templates.
2. Check for renamed variables.
3. Verify conditional blocks still parse.
4. Keep one minimal fallback template ready.

Post-Change Audit Tool

AIOStreams Configuration Checklist

Use this after saving your AIOStreams profile. The checklist is stored locally in this browser.

Service credentials are saved and tested (Debrid/proxy where used) Only required addons are enabled and each timeout is intentional Required/excluded filters were tested against at least 3 sample titles Sort order and dedup mode match your quality-vs-speed goals Formatter preview is clean (no broken tokens or empty lines) You reinstalled only if manifest-structure changes were made Config URL/UUID/password backup is stored safely

Reset Copy status summary

Related Guides

• AIOStreams: Complete Setup and Configuration Guide
• Install & Remove Add-ons Safely (SOP)
• Evaluate Add-on Trust

Sources

• AIOStreams Custom Formatter Wiki
• AIOStreams Setup Guide (Viren’s Guides)
• AIOStreams Documentation V1
• AIOStreams README