Tags

Tags are metadata labels that Zaparoo Core reads from media filenames and from metadata scrapers. They help Core choose between multiple matches for the same title, especially when your library has several regions, languages, revisions, demos, or bad dumps.

You will usually see tags when using title IDs. For example, this launches the US version of Super Mario World when more than one version is available:

@SNES/Super Mario World (region:us)

Tag format

Tags use type:value format. The type is the category, and the value is the specific label.

Part	Example
Tag type	region
Tag value	us
Full tag	region:us

When a tag is part of a title ID, wrap it in parentheses:

@SNES/Game Title (region:eu) (lang:de)

Filename tags

During media database updates, Core can parse known filename markers from ROM sets such as No-Intro and TOSEC. This behavior is controlled by filename_tags, which is enabled by default.

This filename:

Sonic the Hedgehog (USA, Europe) (En,Fr,De) (Rev A).md

can produce tags like:

• region:us
• region:eu
• lang:en
• lang:fr
• lang:de
• rev:a

Core also extracts tags from other recognized markers, including years, disc numbers, versions, dumps, prototypes, demos, translations, unofficial hacks, set numbers, and re-releases.

MiSTer Arcade filenames can include a region and build date in one parenthetical group. For example, (World 931005) becomes region:world and builddate:1993-10-05. Core also accepts YYYYMMDD, YYYY-MM-DD, and comma-separated forms such as (EU, 961004).

Using tags in title IDs

Use tags when a title ID needs to be more specific than the game name alone.

@SNES/Super Mario World
@SNES/Super Mario World (region:us)
@SNES/Super Mario World (region:eu) (lang:de)
@Arcade/X-Men Vs. Street Fighter (region:eu) (builddate:1996-10-04)
@Genesis/Sonic (+unfinished:demo)
@SNES/Game Title (~lang:en) (~lang:fr)

The first example lets Core choose the best match. The others require or exclude specific tagged matches.

Operators

Tags support three operators in title IDs and launch.title tag arguments.

Syntax	Meaning
(tag:value) or (+tag:value)	Match must have this tag.
(-tag:value)	Match must not have this tag.
(~tag:value)	At least one ~ tag must match.

Examples:

@Genesis/Sonic (region:us)
@Genesis/Sonic (-unfinished:demo)
@SNES/Game Title (lang:en) (-unfinished:beta)
@SNES/Game Title (~lang:en) (~lang:fr)

Multiple tags can share one parenthetical group when separated by commas:

@SNES/Game Title (region:us, lang:en)

The tags argument uses the same operators without parentheses:

**launch.title:Genesis/Sonic?tags=region:us,lang:en
**launch.title:Genesis/Sonic?tags=region:us,-unfinished:demo

Matching behavior

When you launch by title ID, Core matches the title first, then uses tags to narrow or rank the results.

Core also filters out some variants by default, including demos, betas, prototypes, hacks, translations, bootlegs, re-releases, and bad dumps. If you want one of those variants, request it with a positive tag:

@Genesis/Sonic (+unfinished:demo)
@SNES/Game Title (+unfinished:beta)
@SNES/Game Title (+unlicensed:translation)

If several good matches remain, Core applies your configured region and language preferences, then other scoring rules such as launcher file type priority and filename quality.

For same-named variants, browse, search, and lookup responses include disambiguatingTags: the tags that distinguish one variant from another. Clients can show those labels to help you pick the right entry, and the generated ZapScript includes the same tags so the token resolves back to that specific variant.

Default regions and languages

Set default preferences in the media config section when you want Core to prefer certain regions or languages without writing tags into every title ID.

[media]
default_regions = ["us", "eu", "world"]
default_langs = ["en", "de"]

With those preferences, @SNES/Super Mario World will prefer matching US, European, or World releases, and English or German language tags, when those tags are present.

Useful tag types

These are the tag types most likely to matter when writing title IDs by hand.

Tag type	Used for	Examples
region	Release region	region:us, region:eu, region:jp, region:world
lang	Language	lang:en, lang:fr, lang:de, lang:ja
rev	Revision or version	rev:a, rev:b, rev:1, rev:prg0
year	Release year	year:1991, year:1996, year:19xx
builddate	ROM set build date, often from arcade filenames	builddate:1996-10-04
unfinished	Pre-release or incomplete builds	unfinished:alpha, unfinished:beta, unfinished:demo, unfinished:proto
dump	Dump quality or dump status	dump:verified, dump:bad, dump:overdump, dump:underdump
unlicensed	Unofficial releases and modifications	unlicensed:bootleg, unlicensed:hack, unlicensed:translation
patch	ROM hacks and patches	patch:fastrom:1-1, patch:uncensored, patch:font:us
rerelease	Digital re-releases and collections	rerelease:virtualconsole:wii, rerelease:mdmini:1
reboxed	Re-releases and packaging variants	reboxed:playerschoice, reboxed:satakore
disc and disctotal	Multi-disc sets	disc:1, disc:2, disctotal:3
media	Media type or side	media:disc, media:tape, media:side-a
set	ROM set number or variant group	set:1, set:2
video	Video standard	video:ntsc, video:pal, video:pal-60

Core defines many more tag types than this, including hardware add-ons, embedded cartridge chips, compatibility tags, publishers, developers, genres, and player counts. Most users do not need to write those by hand.

patch tags come from bracketed patch notes in filenames, such as [FastROM hack by Author v1.1], and let a title ID pick that patched variant of a game.

User tags

A few tags are set by you rather than read from a filename. Favorites, likes, dislikes, and play later come from the Zaparoo App, or from your Zaparoo Online account through Library sync. Frontend sets favorites. They filter like any other tag:

**launch.random:SNES?tags=user:favorite

Tag	Meaning
user:favorite	Marked as a favorite
user:liked, user:disliked	Liked or disliked. Disliking clears favorite and liked
user:playlater	Saved to play later
user:hidden	Hidden from browsing, search, and random picks. A card or script still launches it
user:deck:<id>	In the deck with that ID. Set by the deck, not by hand

Tags are stable

A tag you write in a title ID or a filter should mean the same thing on every device, whichever source the metadata came from, and keep meaning it after an update. So Core controls which tag values exist:

• Most tag types are a fixed list. genre, region, lang, arcadeboard, players, input, the search franchises and features, and most of the filename types in the table above only accept values Core defines. Genres follow GameDataBase, for example genre:shmup:v or genre:action:platformer.
• A few follow a strict format instead of a list: year (1950 to 2099), builddate (a real date), rating (0 to 100), the numbers in disc, disctotal, set, track and episode tags, and the versions in rev and patch.
• Only developer, publisher and credit accept any name, because company names cannot be listed. Core stores them as normalized slugs, so T&E Soft becomes t-and-e-soft, and keeps the original spelling as a label.

Scraped tags

Metadata scrapers cannot add tag types or tag values. A scraper translates what its source says into an existing value: a Shoot'em Up / Vertical genre becomes genre:shmup:v, a game series becomes search:franchise:castlevania, a CPS2 board becomes arcadeboard:capcom:cps2. A value the scraper cannot translate is left out rather than stored as it was written. That keeps filters working across sources, at the cost of dropping the occasional unusual source value until Core learns to map it.

Use the type:value form when writing title IDs or tag filters by hand.

Credit

Zaparoo's tag taxonomy is inspired by GameDataBase, a game metadata project by PigSaint. GameDataBase uses a deeper hierarchical tag system; Zaparoo uses simpler type:value tags for filename parsing and title matching.