QML scripts can be invoked via the context menu of the file list and can be set in the User Actions tab of the settings dialog. The scripts which are set there can be used as examples to program custom scripts. QML uses JavaScript, here is the obligatory "Hello World":

import Kid3 1.0  Kid3Script {   onRun: {     console.log("Hello world, directory is", app.dirName)     Qt.quit()   } } 

Or, in the console:

          console.log("Hello world, directory is", app.dirName)
          script.properties(app)
          console.log(script.properties(app))
        

If this script is saved as /path/to/Example.qml, the user command can be defined as @qml /path/to/Example.qml with name  QML Test and Output checked. It can then be started using the QML Test item in the file list context menu, and the output will be visible in the window. Alternatively, the script could also be started independent of Kid3 using the QML tools.

qml -apptype widget -I /usr/lib/kid3/plugins/imports /path/to/Example.qml 

or

qmlscene -I /usr/lib/kid3/plugins/imports /path/to/Example.qml 

On Windows and OSX, the import path must be adapted to the imports folder inside the installation directory. Scripts started outside of Kid3 will use the current directory, so it should be changed beforehand.

To list the titles in the tags 2 of all files in the current directory, the following script could be used:

          import Kid3 1.0  
          Kid3Script 
          {   
            onRun: 
            {     
              app.firstFile() do 
              {
                if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) 
                {
                  console.log(app.getFrame(tagv2, "title"))       
                }     
              } 
              while (app.nextFile())   
            } 
          } 
        

If the directory contains many files, such a script might block the user interface for some time. For longer operations, it should therefore have a break from time to time. The alternative implementation below has the work for a single file moved out into a function. This function invokes itself with a timeout of 1 ms at the end, given that more files have to be processed. This will ensure that the GUI remains responsive while the script is running.

          import Kid3 1.0  
          Kid3Script 
          {   
            onRun: 
            {     
              function doWork() 
              {
                if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) 
                {
                  console.log(app.getFrame(tagv2, "title"))       
                }       
                if (!app.nextFile()) 
                {
                  Qt.quit()       
                } 
                else 
                {
                  setTimeout(doWork, 1)       
                }     
              }      
              app.firstFile()     
              doWork()   
            } 
          } 
        

When using app.firstFile() with app.nextFile(), all files of the current directory will be processed. If only the selected files shall be affected, use  firstFile() and nextFile() instead, these are convenience functions of the Kid3Script component. The following example is a script which copies only the disc number and copyright frames of the selected file.

          import Kid3 1.1  
          Kid3Script 
          {   
            onRun: 
            {     
              function doWork() 
              {
                if (app.selectionInfo.tag(Frame.Tag_2).tagFormat) 
                {
                  app.setFrame(tagv2, "*.selected", false)         
                  app.setFrame(tagv2, "discnumber.selected", true)         
                  app.setFrame(tagv2, "copyright.selected", true)         
                  app.copyTags(tagv2)       
                }       
                if (!nextFile()) 
                {         
                  Qt.quit()       
                } 
                else 
                {         
                  setTimeout(doWork, 1)       
                }     
              }      
              firstFile()     
              doWork()   
            } 
          } 
        

More example scripts come with Kid3 and are already registered as user commands.

QML API

The 3 APIs can be easily explored using the QML Console. There are 3 root objects: SCRIPT, APP, and CONFIGS.

Kid3Script

Kid3Script is a regular QML component located inside the plugin directory. 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 Object Model

JavaScript, and therefore QML too, has only a limited set of functions for scripting. Therefore, the script object has been added to kid3 and has some additional methods:

        script.properties(obj)
        script.writeFile(filePath, data) 
        script.readFile(filePath)
        script.removeFile(filePath)
        script.fileExists(filePath)
        script.fileIsWritable(filePath)
        script.getFilePermissions(filePath)
        script.setFilePermissions(filePath, modeBits)
        script.classifyFile(filePath): Get class of file (dir "/", 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 directory, true if OK 
        script.removeDir(path): Remove directory, true if OK 
        script.tempPath(): Path to temporary directory 
        script.musicPath(): Path to music directory 
        script.listDir(path, [nameFilters], [classify]): List directory 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 Object Model

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

        app.openDirectory(path): Open directory 
        app.unloadAllTags(): Unload all tags 
        app.saveDirectory(): Save directory 
        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: Directory 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 directory 
      

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 Object Model

Configuration properties are mostly read/write. You can use script.properties() to get inner classes.

        configs.networkConfig()
        configs.networkConfig().useProxy
        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()