Titleformat API

English API reference for the titleformat family.

This page is the primary owner for the namespaces listed below. Method names, parameter keys, and return fields follow the C++ RegisterApi handlers.

titleformat

titleformat.eval

Parameter	Type	Required	Description
path	string	Yes	File path to evaluate the pattern against.
pattern	string	Yes	Titleformat pattern to compile and evaluate.

Returns: {"error":"...","path":"...","pattern":"...","result":"...","success":true}

const { result } = await fb2k.invoke('titleformat.eval', {
    path: 'C:\\Music\\song.flac',
    pattern: '%artist% - %title%'
});

titleformat.evalBatch

Parameter	Type	Required	Description
paths	array	Yes	File path list to evaluate.
pattern	string	Yes	Titleformat pattern compiled once and reused for every path.

Returns: {"error":"...","errorCount":"...","pattern":"...","results":"...","success":true,"successCount":"...","total":"..."}

const { results } = await fb2k.invoke('titleformat.evalBatch', {
    paths: ['C:\\Music\\song.flac', 'C:\\Music\\other.mp3'],
    pattern: '%codec% %bitrate%kbps'
});

titleformat.evalFields

Parameter	Type	Required	Description
fields	object	Yes	Map of result field name to titleformat pattern.
path	string	Yes	File path to evaluate the patterns against.

Returns: {"error":"...","path":"...","success":true}

const result = await fb2k.invoke('titleformat.evalFields', {
    fields: { title: '%title%', artist: '%artist%', length: '%length%' },
    path: 'C:\\Music\\song.flac'
});

titleformat.evalFieldsBatch

Parameter	Type	Required	Description
fields	object	Yes	Map of result field name to titleformat pattern.
paths	array	Yes	File path list to evaluate.

Returns: {"error":"...","errorCount":"...","results":"...","success":true,"successCount":"...","total":"..."}

const { results } = await fb2k.invoke('titleformat.evalFieldsBatch', {
    fields: { title: '%title%', album: '%album%' },
    paths: ['C:\\Music\\song.flac', 'C:\\Music\\other.mp3']
});

titleformat.getBuiltinFields

No parameters.

Returns: {"fields":[],"success":true}

const result = await fb2k.invoke('titleformat.getBuiltinFields');

Evaluation semantics

• titleformat.eval requires a non-empty path and pattern. Invalid patterns and unavailable files return success: false with error.
• titleformat.evalBatch requires an array paths and a non-empty pattern; per-item failures are retained in results, while successCount and errorCount summarize the batch.
• titleformat.evalFields and titleformat.evalFieldsBatch require an object fields. Each key becomes a response property; non-string field expressions are returned as null for that key.
• titleformat.getBuiltinFields is a convenience reference generated by the runtime. It does not guarantee that optional component fields such as play-count data are populated for every installation or track.