Documentation/FbMetadbHandleList
class

FbMetadbHandleList

js/foo_uie_jsplitter.js:3488
FbMetadbHandleList(arg)

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

Parameters

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

Count

js/foo_uie_jsplitter.js:3495
Count: number

Example

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

Add

js/foo_uie_jsplitter.js:3505
Add(handle)

Parameters

NameTypeDescription
handleFbMetadbHandle

Returns

number

Example

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

AddRange

js/foo_uie_jsplitter.js:3514
AddRange(handle_list)

Parameters

NameTypeDescription
handle_listFbMetadbHandleList

Example

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

AttachImage

js/foo_uie_jsplitter.js:3522
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.

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);
method

AttachImage2

js/foo_uie_jsplitter.js:3550
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);
method

BSearch

js/foo_uie_jsplitter.js:3580
BSearch(handle)

Faster than Find.

Parameters

NameTypeDescription
handleFbMetadbHandle

Must be sorted with Sort.

Returns

number

-1 on failure.

method

CalcTotalDuration

js/foo_uie_jsplitter.js:3588
CalcTotalDuration()

Returns

float

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

method

CalcTotalSize

js/foo_uie_jsplitter.js:3593
CalcTotalSize()

Returns

number

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

method

Clone

js/foo_uie_jsplitter.js:3598
Clone()

Returns

FbMetadbHandleList

Example

let handle_list2 = handle_list.Clone();
method

Convert

js/foo_uie_jsplitter.js:3606
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
}
method

Find

js/foo_uie_jsplitter.js:3621
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

method

GetLibraryRelativePaths

js/foo_uie_jsplitter.js:3629
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();
method

GetOtherInfo

js/foo_uie_jsplitter.js:3643
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);
method

Insert

js/foo_uie_jsplitter.js:3656
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());
method

InsertRange

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

Parameters

NameTypeDescription
indexnumber
handle_listFbMetadbHandleList
method

MakeDifference

js/foo_uie_jsplitter.js:3672
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.
method

MakeIntersection

js/foo_uie_jsplitter.js:3690
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"
method

MakeUnion

js/foo_uie_jsplitter.js:3707
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
method

OptimiseFileLayout

js/foo_uie_jsplitter.js:3724
OptimiseFileLayout(minimise)

Parameters

NameTypeDescription
minimiseboolean

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

method

OrderByFormat

js/foo_uie_jsplitter.js:3732
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);
method

OrderByPath

js/foo_uie_jsplitter.js:3743
OrderByPath()

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

method

OrderByRelativePath

js/foo_uie_jsplitter.js:3750
OrderByRelativePath()
method

RefreshStats

js/foo_uie_jsplitter.js:3753
RefreshStats()
method

Remove

js/foo_uie_jsplitter.js:3758
Remove(handle)

Parameters

NameTypeDescription
handleFbMetadbHandle
method

RemoveAll

js/foo_uie_jsplitter.js:3763
RemoveAll()
method

RemoveAttachedImage

js/foo_uie_jsplitter.js:3766
RemoveAttachedImage(art_id)

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

Parameters

NameTypeDescription
art_id = 0optionalnumber

See AlbumArtId

method

RemoveAttachedImages

js/foo_uie_jsplitter.js:3773
RemoveAttachedImages()

Removes all attached images.

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

method

RemoveById

js/foo_uie_jsplitter.js:3780
RemoveById(idx)

Parameters

NameTypeDescription
idxnumber

Example

handle_list.RemoveById(0);
method

RemoveRange

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

Parameters

NameTypeDescription
fromnumber
numnumber

Example

handle_list.RemoveRange(10, 20);
method

SaveAs

js/foo_uie_jsplitter.js:3797
SaveAs(path)

Parameters

NameTypeDescription
pathstring
method

Sort

js/foo_uie_jsplitter.js:3803
Sort()

Remove duplicates and optimise for other handle list operations

method

UpdateFileInfoFromJSON

js/foo_uie_jsplitter.js:3810
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));