The API can be easily explored using the QML Console, which is available as an example script with a user interface.
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
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
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) }
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()