QML API

The API can be easily explored using the QML Console, which is available as an example script with a user interface.

Kid3Script

Kid3Script is a regular QML component located inside the plugin folder. You could use another QML component just as well. Using Kid3Script makes it easy to start the script function using the onRun signal handler. Moreover it offers some functions:

onRun: Signal handler which is invoked when the script is started
tagv1, tagv2, tagv2v1: Constants for tag parameters
script: Access to scripting functions
configs: Access to configuration objects
getArguments(): List of script arguments
isStandalone(): true if the script was not started from within Kid3
setTimeout(callback, delay): Starts callback after delay ms
firstFile(): To first selected file
nextFile(): To next selected file

Scripting Functions

As JavaScript and therefore QML too has only a limited set of functions for scripting, the script object has some additional methods, for instance:

script.properties(obj): String with Qt properties
script.writeFile(filePath, data): Write data to file, true if OK
script.readFile(filePath): Read data from file
script.removeFile(filePath): Delete file, true if OK
script.fileExists(filePath): true if file exists
script.fileIsWritable(filePath): true if file is writable
script.getFilePermissions(filePath): Get file permission mode bits
script.setFilePermissions(filePath, modeBits): Set file permission mode bits
script.classifyFile(filePath): Get class of file (folder "/", symlink "@", exe "*",
  file " ")
script.renameFile(oldName, newName): Rename file, true if OK
script.copyFile(source, dest): Copy file, true if OK
script.makeDir(path): Create folder, true if OK
script.removeDir(path): Remove folder, true if OK
script.tempPath(): Path to temporary folder
script.musicPath(): Path to music folder
script.listDir(path, [nameFilters], [classify]): List folder entries
script.system(program, [args], [msecs]): Synchronously start a system command,
  [exit code, standard output, standard error] if not timeout
script.systemAsync(program, [args], [callback]): Asynchronously start a system
command, callback will be called with [exit code, standard output, standard
error]
script.getEnv(varName): Get value of environment variable
script.setEnv(varName, value): Set value of environment variable
script.getQtVersion(): Qt version string, e.g. "5.4.1"
script.getDataMd5(data): Get hex string of the MD5 hash of data
script.getDataSize(data): Get size of byte array
script.dataToImage(data, [format]): Create an image from data bytes
script.dataFromImage(img, [format]): Get data bytes from image
script.loadImage(filePath): Load an image from a file
script.saveImage(img, filePath, [format]): Save an image to a file, true if OK
script.imageProperties(img): Get properties of an image, map containing
  "width", "height", "depth" and "colorCount", empty if invalid image
script.scaleImage(img, width, [height]): Scale an image, returns scaled image

Application Context

Using QML, a large part of the Kid3 functions are accessible. The API is similar to the one used for D-Bus. For details, refer to the respective notes.

app.openDirectory(path): Open folder
app.unloadAllTags(): Unload all tags
app.saveDirectory(): Save folder
app.revertFileModifications(): Revert
app.importTags(tag, path, fmtIdx): Import file
app.importFromTags(tag, source, extraction): Import from tags
app.importFromTagsToSelection(tag, source, extraction): Import from tags of selected files
app.downloadImage(url, allFilesInDir): Download image
app.exportTags(tag, path, fmtIdx): Export file
app.writePlaylist(): Write playlist
app.getPlaylistItems(path): Get items of a playlist
app.setPlaylistItems(path, items): Set items of a playlist
app.selectAllFiles(): Select all
app.deselectAllFiles(): Deselect
app.firstFile([select], [onlyTaggedFiles]): To first file
app.nextFile([select], [onlyTaggedFiles]): To next file
app.previousFile([select], [onlyTaggedFiles]): To previous file
app.selectCurrentFile([select]): Select current file
app.selectFile(path, [select]): Select a specific file
app.getSelectedFilePaths([onlyTaggedFiles]): Get paths of selected files
app.requestExpandFileList(): Expand all
app.applyFilenameFormat(): Apply filename format
app.applyTagFormat(): Apply tag format
app.applyTextEncoding(): Apply text encoding
app.numberTracks(nr, total, tag, [options]): Number tracks
app.applyFilter(expr): Filter
app.convertToId3v23(): Convert ID3v2.4.0 to ID3v2.3.0
app.convertToId3v24(): Convert ID3v2.3.0 to ID3v2.4.0
app.getFilenameFromTags(tag): Filename from tags
app.getTagsFromFilename(tag): Filename to tags
app.getAllFrames(tag): Get object with all frames
app.getFrame(tag, name): Get frame
app.setFrame(tag, name, value): Set frame
app.getPictureData(): Get data from picture frame
app.setPictureData(data): Set data in picture frame
app.copyToOtherTag(tag): Tags to other tags
app.copyTags(tag): Copy
app.pasteTags(tag): Paste
app.removeTags(tag): Remove
app.playAudio(): Play
app.readConfig(): Read configuration
app.applyChangedConfiguration(): Apply configuration
app.dirName: Folder name
app.selectionInfo.fileName: File name
app.selectionInfo.filePath: Absolute file path
app.selectionInfo.detailInfo: Format details
app.selectionInfo.tag(Frame.Tag_1).tagFormat: Tag 1 format
app.selectionInfo.tag(Frame.Tag_2).tagFormat: Tag 2 format
app.selectionInfo.formatString(tag, format): Substitute codes in format string
app.selectFileName(caption, dir, filter, saveFile): Open file dialog to
select a file
app.selectDirName(caption, dir): Open file dialog to select a folder

For asynchronous operations, callbacks can be connected to signals.

function automaticImport(profile) {
  function onAutomaticImportFinished() {
    app.batchImporter.finished.disconnect(onAutomaticImportFinished)
  }
  app.batchImporter.finished.connect(onAutomaticImportFinished)
  app.batchImport(profile, tagv2)
}

function renameDirectory(format) {
  function onRenameActionsScheduled() {
    app.renameActionsScheduled.disconnect(onRenameActionsScheduled)
    app.performRenameActions()
  }
  app.renameActionsScheduled.connect(onRenameActionsScheduled)
  app.renameDirectory(tagv2v1, format, false)
}

Configuration Objects

The different configuration sections are accessible via methods of configs. Their properties can be listed in the QML console.

script.properties(configs.networkConfig())

Properties can be set:

configs.networkConfig().useProxy = false

configs.batchImportConfig()
configs.exportConfig()
configs.fileConfig()
configs.filenameFormatConfig()
configs.filterConfig()
configs.findReplaceConfig()
configs.guiConfig()
configs.importConfig()
configs.mainWindowConfig()
configs.networkConfig()
configs.numberTracksConfig()
configs.playlistConfig()
configs.renDirConfig()
configs.tagConfig()
configs.tagFormatConfig()
configs.userActionsConfig()