L'API es pot explorar amb facilitat utilitzant la consola QML, la qual està disponible com un script d'exemple amb una interfície d'usuari.
El Kid3Script
és un component QML regular ubicat a dins de la carpeta del connector. També podria emprar un altre connector QML. L'ús del Kid3Script
facilita l'inici de la funció de script utilitzant el controlador del senyal onRun
. A més ofereix algunes funcions:
onRun: controlador del senyal que s'invoca quan s'inicia l'script tagv1, tagv2, tagv2v1: constants per als paràmetres d'etiqueta script: accés a les funcions per a la creació de scripts configs: accés als objectes de la configuració getArguments(): llista d'arguments de l'script isStandalone(): cert si l'script no es va iniciar des del Kid3 setTimeout (crida de retorn, retard): inicia la crida de retorn després del retard en ms firstFile(): al primer fitxer seleccionat NextFile(): al següent fitxer seleccionat
Com al JavaScript, el QML també té només un conjunt limitat de funcions per a la creació de scripts, l'objecte script
té alguns mètodes addicionals, per exemple:
script.properties(obj): cadena amb les propietats de les Qt script.writeFile(filePath, dades): escriu les dades al fitxer, cert si va bé script.readFile(filePath): llegeix les dades del fitxer script.removeFile(filePath): elimina un fitxer, cert si va bé script.fileExists(filePath): cert si el fitxer existeix script.fileIsWritable(filePath): cert si el fitxer és d'escriptura script.getFilePermissions(filePath): obté els bits per al mode de permís del fitxer script.setFilePermissions(filePath, modeBits): estableix els bits per al mode de permís del fitxer script.classifyFile(filePath): obté la classe de fitxer (carpeta «/», enllaç simbòlic «@», executable «*», fitxer «») script.renameFile(oldname, NEWNAME): canvia el nom del fitxer, cert si va bé script.copyFile(font, dest): copia un fitxer, cert si va bé script.makeDir(camí): crea una carpeta, cert si va bé script.removeDir(camí): elimina una carpeta, cert si va bé script.tempPath(): camí de la carpeta temporal script.musicPath(): camí de la carpeta de música script.listDir(camí, [nameFilters], [classify]): llista les entrades de la carpeta script.system(programa, [args], [msecs]): inicia de mode sincrònic una ordre del sistema, [codi de sortida, sortida estàndard, error estàndard] si no és temps d'espera script.systemAsync(programa, [args], [callback]): inicia una ordre del sistema en el mode asíncron, la crida de retorn es cridarà amb [codi de sortida, sortida estàndard, error estàndard] script.getEnv(varname): obté el valor de la variable d'entorn script.setEnv(varname, valor): estableix el valor a partir de la variable d'entorn script.getQtVersion(): cadena de versió de les Qt, p. ex., «5.4.1» script.getDataMd5(dades): obté una cadena hexadecimal per a la suma MD5 de les dades script.getDataSize(data): obté la mida de la matriu de bytes script.dataToImage(dades, [format]): crea una imatge a partir dels bytes de les dades script.dataFromImage(imatge, [format]): obté els bytes de les dades de la imatge script.loadImage(filePath): carrega una imatge des d'un fitxer script.saveImage(imatge, filePath, [format]): desa una imatge en un fitxer, cert si va bé script.imageProperties(imatge): obté les propietats d'una imatge, un mapa que contindrà «amplada», «alçada», «profunditat» i «colorCount», buit si la imatge no és vàlida script.scaleImage(imatge, amplada, [alt]): escala una imatge, retornarà una imatge escalada
Emprant QML, es pot accedir a una gran part de les funcions del Kid3. L'API és similar a la utilitzada per al D-Bus. Per a més detalls, consulteu les respectives notes.
app.openDirectory(camí): obre la carpeta app.unloadAllTags(): descarrega totes les etiquetes app.saveDirectory(): desa la carpeta app.revertFileModifications(): reverteix app.importTags(etiqueta, camí, fmtIdx): importa el fitxer app.importFromTags(etiqueta, font, extracció): importa des de les etiquetes app.importFromTagsToSelection(etiqueta, font, extracció): importa des de les etiquetes dels fitxers seleccionats app.downloadImage(url, allFilesInDir): descarrega la imatge app.exportTags(etiqueta, camí, fmtIdx): fitxer d'exportació app.writePlaylist(): escriu una llista de reproducció app.getPlaylistItems(camí): obté els elements d'una llista de reproducció app.setPlaylistItems(camí, elements): estableix els elements d'una llista de reproducció app.selectAllFiles(): ho selecciona tot app.deselectAllFiles(): desselecciona app.firstFile([select], [onlyTaggedFiles]): al primer fitxer app.nextFile([select], [onlyTaggedFiles]): al següent fitxer app.previousFile([select], [onlyTaggedFiles]): al fitxer anterior app.selectCurrentFile([select]): selecciona el fitxer actual app.selectFile(camí, [select]): selecciona un fitxer específic app.getSelectedFilePaths([onlyTaggedFiles]): obté els camins dels fitxers seleccionats app.requestExpandFileList(): ho expandeix tot app.applyFilenameFormat(): aplica el format al nom del fitxer app.applyTagFormat(): aplicar el format a l'etiqueta app.applyTextEncoding(): aplica la codificació del text app.numberTracks(núm., total, etiqueta, [options]): números de peça app.applyFilter(expr): filtre app.convertToId3v23(): converteix ID3 versió 2.4.0 a 2.3.0 app.convertToId3v24(): converteix ID3 versió 2.3.0 a 2.4.0 app.getFilenameFromTags(etiqueta): nom de fitxer a partir de les etiquetes app.getTagsFromFilename(etiqueta): nom de fitxer a les etiquetes app.getAllFrames(etiqueta): obté un objecte amb tots els marcs app.getFrame(etiqueta, nom): obté un marc app.setFrame(etiqueta, nom, valor): estableix un marc app.getPictureData(): obté les dades a partir del marc de la imatge app.setPictureData(dades): estableix les dades al marc de la imatge app.copyToOtherTag(etiqueta): etiquetes a altres etiquetes app.copyTags(etiqueta): copia app.pasteTags(etiqueta): enganxa app.removeTags(etiqueta): elimina app.playAudio(): reprodueix app.readConfig(): llegeix la configuració app.applyChangedConfiguration(): aplica la configuració app.dirName: nom de la carpeta app.selectionInfo.fileName: nom del fitxer app.selectionInfo.filePath: camí absolut cap al fitxer app.selectionInfo.detailInfo: detalls del format app.selectionInfo.tag(Frame.Tag_1).tagFormat: format de l'etiqueta 1 app.selectionInfo.tag(Frame.Tag_2).tagFormat: format de l'etiqueta 2 app.selectionInfo.formatString(etiqueta, format): substitueix els codis en una cadena de format app.selectFileName(subtítol, carpeta, filtre, desa el fitxer): obre el diàleg de fitxers i en selecciona un app.selectDirName(títol, carpeta): obre el diàleg de fitxers per a seleccionar una carpeta
Per a operacions asíncrones, les crides de retorn podran connectar-se amb els senyals.
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) }
Es pot accedir a les diferents seccions de configuració a través de mètodes de configs
. Les seves propietats es poden llistar a la consola QML.
script.properties(configs.networkConfig())
Es poden establir les propietats:
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()