Documentation/FbMetadbHandleList
classWORKERCLONEABLE

FbMetadbHandleList

js/foo_uie_jsplitter.js:5520
FbMetadbHandleList(arg)

Handle list elements can be accessed with array accessor, e.g. handle_list[i]

Parameters

NameTypeDescription
argoptionalFbMetadbHandleList | FbMetadbHandle | Array<FbMetadbHandle> | null | undefined
propertyWORKERreadonly

Count

js/foo_uie_jsplitter.js:5529
Count: number

Example

 let handle_list = plman.GetPlaylistItems(plman.ActivePlaylist);
console.log(handle_list.Count);
methodWORKER

Add

js/foo_uie_jsplitter.js:5540
Add(handle)

Parameters

NameTypeDescription
handleFbMetadbHandle

Returns

number

Example

handle_list.Add(fb.GetNowPlaying());
methodWORKER

AddRange

js/foo_uie_jsplitter.js:5550
AddRange(handle_list)

Parameters

NameTypeDescription
handle_listFbMetadbHandleList

Example

handle_list.AddRange(fb.GetLibraryItems());
methodWORKER

AttachImage

js/foo_uie_jsplitter.js:5559
AttachImage(image_path, art_id)

Embeds covers of the specified type, loaded from the specified file, into media files
Any existing artwork of the specified type will be overwritten!
Embedding covers is an asynchronous operation, so its result is not controlled here in any way. However, all the work of the method up to this point (reading file, creating art data) will return false in case of an error.

Relative filesystem paths are resolved as described in utils.ReadTextFile. URLs and foobar2000 URI paths are passed through unchanged.

Parameters

NameTypeDescription
image_pathstring

path to an existing image

art_id = AlbumArtId.frontoptionalAlbumArtId

See AlbumArtId

Returns

boolean —

Returns false if any error occurred before the embedding started, otherwise true

Examples

include(`${fb.ComponentPath}docs\\Flags.js`);

const handle_list = plman.GetPlaylistItems(plman.ActivePlaylist);
if (handle_list.Count > 0) {
   const img_path = 'C:\\path\\to\\image.jpg';
   handle_list.AttachImage(img_path, AlbumArtId.front);
}
include(`${fb.ComponentPath}docs\\Flags.js`);

// since there is no handle method, do this for a single item
const handle_list = new FbMetadbHandleList(fb.GetFocusItem());
const img_path = "C:\\path\\to\\image.jpg";
handle_list.AttachImage(img_path, AlbumArtId.front);
methodWORKER

AttachImage2

js/foo_uie_jsplitter.js:5590
AttachImage2(image, art_id, codec, quality)

Embeds covers of the specified type from exisiting GdiBitmap or D2DBitmap object. Supports JPEG, WEBP and PNG codecs for encoding image before embedding.
Any existing artwork of the specified type will be overwritten!
Embedding covers is an asynchronous operation, so its result is not controlled here in any way. However, all the work of the method up to this point (encoding, creating art data) will return false in case of an error.

Parameters

NameTypeDescription
imageGdiBitmap

(or D2DBitmap if window.DrawMode == 1). Image to attach

art_id = AlbumArtId.frontoptionalAlbumArtId

See AlbumArtId

codec = AttachImage2Codec.JpegoptionalAttachImage2Codec

See AttachImage2Codec

quality = 70.0optionalfloat

NOTE: For WebP quality 100 means lossless WebP; values below 100 use lossy WebP. For PNG quality is ignored because PNG codec is always lossless.

Returns

boolean —

Returns false if any error occurred before the embedding started, otherwise true

Examples

include(`${fb.ComponentPath}docs\\Flags.js`);

const handle_list = plman.GetPlaylistItems(plman.ActivePlaylist);
if (handle_list.Count > 0) {
   const img = gdi.Image("C:\\path\\to\\image.jpg");
   handle_list.AttachImage2(img, AlbumArtId.front, AttachImage2Codec.WebP, 60);
}
* include(`${fb.ComponentPath}docs\\Flags.js`);

// since there is no handle method, do this for a single item
const handle_list = new FbMetadbHandleList(fb.GetFocusItem());
const img = gdi.Image("C:\\path\\to\\image.jpg");
handle_list.AttachImage2(img, AlbumArtId.front, AttachImage2Codec.WebP, 60);
methodWORKER

BSearch

js/foo_uie_jsplitter.js:5621
BSearch(handle)

Faster than Find.

Parameters

NameTypeDescription
handleFbMetadbHandle

Must be sorted with Sort.

Returns

number —

-1 on failure.

methodWORKER

CalcTotalDuration

js/foo_uie_jsplitter.js:5630
CalcTotalDuration()

Returns

float —

total duration in seconds. For display purposes, consider using utils.FormatDuration on the result.

methodWORKER

CalcTotalSize

js/foo_uie_jsplitter.js:5636
CalcTotalSize()

Returns

number —

total size in bytes. For display purposes, consider using utils.FormatFileSize on the result.

methodWORKER

Clone

js/foo_uie_jsplitter.js:5642
Clone()

Returns

FbMetadbHandleList

Example

let handle_list2 = handle_list.Clone();
methodWORKER

Convert

js/foo_uie_jsplitter.js:5651
Convert()

Converts FbMetadbHandleList to an array of FbMetadbHandle.
Use this instead of looping through FbMetadbHandleList, if the playlist is big or if you need to loop multiple times.

Returns

Array<FbMetadbHandle>

Example

let playlist_items_array = plman.GetPlaylistItems(plman.ActivePlaylist).Convert();
for (let i = 0; i < playlist_items_array.length; ++i) {
   // do something with playlist_items_array[i] which is your handle
}
methodWORKER

Find

js/foo_uie_jsplitter.js:5667
Find(handle)

Performance note: if sorted with Sort, use BSearch instead.

Parameters

NameTypeDescription
handleFbMetadbHandle

Returns

number —

index in the handle list on success, -1 if not found

methodWORKERMAIN THREAD

GetLibraryRelativePaths

js/foo_uie_jsplitter.js:5676
GetLibraryRelativePaths()

See fb.GetLibraryRelativePath.

This should be faster than looping a handle list manually and using the aforementioned method.

Returns

Array<string>

Example

let handle_list = fb.GetLibraryItems();
handle_list.OrderByRelativePath();
let relative_paths = handle_list.GetLibraryRelativePaths();
methodWORKER

GetOtherInfo

js/foo_uie_jsplitter.js:5692
GetOtherInfo()

Provides all the information viewable on the Details tab in the main Properties dialog. This can be technical/location info as well as database fields from 3rd party components if present.
This returns a JSON object in string form so you need to use JSON.parse on the result.

Returns

string

Example

const handle_list = plman.GetPlaylistItems(plman.ActivePlaylist);
const str = handle_list.GetOtherInfo();
console.log(str);
methodWORKER

Insert

js/foo_uie_jsplitter.js:5706
Insert(index, handle)

Parameters

NameTypeDescription
indexnumber
handleFbMetadbHandle

Example

// This inserts at the end of the handle list.
handle_list.Insert(handle_list.Count, fb.GetNowPlaying());
methodWORKER

InsertRange

js/foo_uie_jsplitter.js:5717
InsertRange(index, handle_list)

Parameters

NameTypeDescription
indexnumber
handle_listFbMetadbHandleList
methodWORKER

MakeDifference

js/foo_uie_jsplitter.js:5724
MakeDifference(handle_list)

Note: sort with FbMetadbHandleList#Sort before using.

Parameters

NameTypeDescription
handle_listFbMetadbHandleList

Sorted handle list.

Example

let one = plman.GetPlaylistItems(0);
one.Sort();

let two = plman.GetPlaylistItems(1);
two.Sort();

one.MakeDifference(two);
// "one" now only contains handles that were unique to "one".
// Anything that also existed in "two" will have been removed.
methodWORKER

MakeIntersection

js/foo_uie_jsplitter.js:5743
MakeIntersection(handle_list)

Note: sort with Sort before using.

Parameters

NameTypeDescription
handle_listFbMetadbHandleList

Sorted handle list.

Example

let one = plman.GetPlaylistItems(0);
one.Sort();

let two = plman.GetPlaylistItems(1);
two.Sort();

one.MakeIntersection(two);
// "one" now only contains handles that were in BOTH "one" AND "two"
methodWORKER

MakeUnion

js/foo_uie_jsplitter.js:5761
MakeUnion(handle_list)

Note: sort with Sort before using.

Parameters

NameTypeDescription
handle_listFbMetadbHandleList

Sorted handle list.

Example

let one = plman.GetPlaylistItems(0);
one.Sort();

let two = plman.GetPlaylistItems(1);
two.Sort();

one.MakeUnion(two);
// "one" now contains all handles from "one" AND "two" with any duplicates removed
methodWORKERMAIN THREAD

OptimiseFileLayout

js/foo_uie_jsplitter.js:5779
OptimiseFileLayout(minimise)

Parameters

NameTypeDescription
minimiseboolean

This provides the same functionality as the native context menu items under Utilities except there are no prompts.

methodWORKER

OrderByFormat

js/foo_uie_jsplitter.js:5789
OrderByFormat(tfo, direction)

Parameters

NameTypeDescription
tfoFbTitleFormat

An instance of FbTitleFormat.

directionnumber

> 0 - ascending.

Example

let handle_list = fb.GetLibraryItems();
let tfo = fb.TitleFormat("%album artist%|%date%|%album%|%discnumber%|%tracknumber%");
handle_list.OrderByFormat(tfo, 1);
methodWORKER

OrderByPath

js/foo_uie_jsplitter.js:5801
OrderByPath()

Note: this method should only be used on a handle list containing items that are monitored as part of the Media Library.

methodWORKERMAIN THREAD

OrderByRelativePath

js/foo_uie_jsplitter.js:5809
OrderByRelativePath()
methodWORKERMAIN THREAD

RefreshStats

js/foo_uie_jsplitter.js:5816
RefreshStats()
methodWORKER

Remove

js/foo_uie_jsplitter.js:5823
Remove(handle)

Parameters

NameTypeDescription
handleFbMetadbHandle
methodWORKER

RemoveAll

js/foo_uie_jsplitter.js:5829
RemoveAll()
methodWORKERMAIN THREAD

RemoveAttachedImage

js/foo_uie_jsplitter.js:5835
RemoveAttachedImage(art_id)

Note: a progress dialog will be shown for larger file selections.

Parameters

NameTypeDescription
art_id = 0optionalnumber

See AlbumArtId

methodWORKERMAIN THREAD

RemoveAttachedImages

js/foo_uie_jsplitter.js:5844
RemoveAttachedImages()

Removes all attached images.

Note: a progress dialog will be shown for larger file selections.

methodWORKER

RemoveById

js/foo_uie_jsplitter.js:5853
RemoveById(idx)

Parameters

NameTypeDescription
idxnumber

Example

handle_list.RemoveById(0);
methodWORKER

RemoveRange

js/foo_uie_jsplitter.js:5862
RemoveRange(from, num)

Parameters

NameTypeDescription
fromnumber
numnumber

Example

handle_list.RemoveRange(10, 20);
methodWORKER

Reverse

js/foo_uie_jsplitter.js:5872
Reverse()

Reverses the order of the items in the handle list.

methodWORKER

SaveAs

js/foo_uie_jsplitter.js:5884
SaveAs(path)

Saves the handle list as a playlist. The output format is selected by foobar2000 from the filename extension.

Relative filesystem paths are resolved as described in utils.ReadTextFile. URLs and foobar2000 URI paths are passed through unchanged.

Parameters

NameTypeDescription
pathstring
methodWORKER

Shuffle

js/foo_uie_jsplitter.js:5878
Shuffle()

Randomly shuffles the items in the handle list.

methodWORKER

Sort

js/foo_uie_jsplitter.js:5895
Sort()

Remove duplicates and optimise for other handle list operations

methodWORKERMAIN THREAD

UpdateFileInfoFromJSON

js/foo_uie_jsplitter.js:5903
UpdateFileInfoFromJSON(str)

Updated metadb tags with new values.

Parameters

NameTypeDescription
strstring

JSON string, which contains an object (applies same values to every track) or an array of objects (one object per track).

Example

// assume we've selected one album
let handles = plman.GetPlaylistSelectedItems(plman.ActivePlaylist);

let arr = [];
for (let i = 0; i < handles.Count; ++i) {
    // each element of the array must be an object of key names/values, indicated by the curly braces
    arr.push({
        'tracknumber' : i + 1, // independent values per track
        'totaltracks' : handles.Count,
        'album' : 'Greatest Hits', // a simple string for a single value
        'genre' : ['Rock', 'Hard Rock'], // we can use an array here for multiple value tags
        'bad_tag' : '' // blank values will clear any existing tags.
    });
}

handles.UpdateFileInfoFromJSON(JSON.stringify(arr));