From 0b439cba307cd005e90cc723fca6ddb57b7403ff Mon Sep 17 00:00:00 2001 From: Alexey Vazhnov Date: Wed, 22 Oct 2025 18:10:39 +0200 Subject: [PATCH 1/7] Rename "docs.txt" into "docs.rst" to be recognisible as reStructuredText; remove extra spaces --- docs.txt => docs.rst | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) rename docs.txt => docs.rst (95%) diff --git a/docs.txt b/docs.rst similarity index 95% rename from docs.txt rename to docs.rst index cd20cae..20cb549 100644 --- a/docs.txt +++ b/docs.rst @@ -17,8 +17,8 @@ General settings A) Keep any pvr information -When enabled the add-on will not delete any references to files recorded with a -live-tv backend. +When enabled the add-on will not delete any references to files recorded with a +live-tv backend. B) Keep bookmarked files @@ -27,15 +27,15 @@ in a path that would have been deleted otherwise. C) Automatically trigger clean library -When enabled, the add-on will call Kodi's built in 'clean library' routine after it +When enabled, the add-on will call Kodi's built in 'clean library' routine after it has finished it's own cleaning. This cleans the other tables in the database that the add-on doesn't touch. It is recommended that this setting is left enabled at all times. -Run clean library 2-6 times -*Kodi will sometimes require multiple passes to clean all the paths that it can potentially clean -(This is because of "cascading" effects of removing invalid files, invalid paths and invalid -parent paths). -When enabled,this option will run Clean Library a number of additonal times, from 2-6, until there are +*Kodi will sometimes require multiple passes to clean all the paths that it can potentially clean +(This is because of "cascading" effects of removing invalid files, invalid paths and invalid +parent paths). +When enabled,this option will run Clean Library a number of additonal times, from 2-6, until there are the same number of paths and files left at the end. D) Back-up local database before cleaning @@ -50,7 +50,7 @@ E) Show summary window When enabled, a pop-up window will list various settings and paths, depending upon the options chosen in the add-on settings. It is possible to abort the add-on run at this point which will -leave the database un-touched, or to select the 'Do It !!' button which will run the cleaning +leave the database un-touched, or to select the 'Do It !!' button which will run the cleaning routine with the chosen settings. If this setting is disabled, the add-on will run without user intervention although any logs will still be created. @@ -59,9 +59,9 @@ Debug and log settings A) Log paths to database-cleaner.log -If enabled the add-on will create a logfile in Kodi's 'temp' directory that records all the +If enabled the add-on will create a logfile in Kodi's 'temp' directory that records all the paths that the add-on will delete. If 'show summary window' is enabled it is possible to stop -the add-on by pressing the 'abort' button. The logfile will still be created so that users can +the add-on by pressing the 'abort' button. The logfile will still be created so that users can see what will be deleted before actually doing so. When the add-on cleans the video database, any existing log will be backed-up to 'database-cleaner.old.log'. @@ -93,7 +93,7 @@ B) Use sources.xml on this machine Generally, this setting should be enabled. Users of MySQL databases do not need to have a 'sources.xml' on each machine that their database is shared with, because the paths are contained within the shared database. Such users can disable this setting and can then set the path to a 'sources.xml' on a different networked -machine. This means MySQL users can run the add-on on any of their machines whilst only having a +machine. This means MySQL users can run the add-on on any of their machines whilst only having a 'sources.xml' on one machine. Advanced @@ -118,26 +118,26 @@ the 'do it !!' button is pressed. C) Replace path in database -If enabled the user must specify an existing path and a new path. Any paths containing the -specified existing path will be renamed to the new path. This is useful if you move a +If enabled the user must specify an existing path and a new path. Any paths containing the +specified existing path will be renamed to the new path. This is useful if you move a directory on disk but do not want to remove and re-scan the source in Kodi. The add-on generates the list of paths by appending a wildcard to the supplied 'old path'. This means that a supplied path of 'nfs://OLD_SERVER' will include 'nfs://OLD_SERVER/Movies' and any other -directories in the tree. If the new path were 'nfs://NEW_SERVER' then every path starting with +directories in the tree. If the new path were 'nfs://NEW_SERVER' then every path starting with 'nfs://OLD_SERVER' will become 'nfs://NEW_SERVER' eg with the Movies directory above, the path would become 'nfs://NEW_SERVER/Movies'. Renaming a path automatically turns off once the path -has been renamed. Again, it is possible by aborting the add-on in the summary window to generate a +has been renamed. Again, it is possible by aborting the add-on in the summary window to generate a logfile showing the original path and the new path to aid users in determining if everything is correct. Clicking on the 'Do it !' button or turning off the summary window will rename the path(s) and turn this setting off. -NOTE - Paths should NOT end with a terminating slash (either '\' or '/' depending on your OS) as this will lead to +NOTE - Paths should NOT end with a terminating slash (either '\' or '/' depending on your OS) as this will lead to double slashes being inserted into the database. texturecache.py +++++++++++++++ Inclusion of texturecache.py (by Milhouse): -Additional settings in the Video Database Cleaner addon to allow user to run texturecache.py +Additional settings in the Video Database Cleaner addon to allow user to run texturecache.py after the Video Database Cleaner has completed cleaning the MyMovies.db. Additional settings allow the user to: a. Enable or Disable the running of texturecache.py at the end of the Video Database cleanup @@ -160,11 +160,11 @@ Deep Clean ++++++++++ WARNING - CAN BE VERY SLOW! (it will probe every physical file/directory as well as all that are listed in the database) -This option manually scans the locations listed in sources.xml, and builds a list of current, legitimate directories and files. +This option manually scans the locations listed in sources.xml, and builds a list of current, legitimate directories and files. It doesn't know or care if directories are removable media/network storage/mount points and ignores the 'keep bookmarks' function and doesn't work on the 'remove specific path' operations (only on the general cleaning operations). Once it has the list of exisiting, legitimate media files, it will compare this to the database and remove any enries that do not correspond. -*This is helpful when there have been a lot of manualy deleted files/folders that the built in Kodi Video cleaner dos not clean up. +*This is helpful when there have been a lot of manualy deleted files/folders that the built in Kodi Video cleaner dos not clean up. It will help to remove many of the "directory does not exist" erros in the kodi.log file - Files and Paths only in one directory: - This can help to focus the Deep Clean on a specific directory, instaed of all media. @@ -179,7 +179,7 @@ run. No other cleaning will be done however. To run the add-on silently as a scheduled task, turn OFF 'Show summary window' in general settings. -To remove old links, streaming info and general rubbish accumulated in the database, ensure that +To remove old links, streaming info and general rubbish accumulated in the database, ensure that 'use sources.xml to determine files to keep' is turned ON. If you have a PVR backend, turn on 'keep any pvr information' otherwise all information relating to your recordings will be deleted. From f78d50ce456a18d52d85e0dce3172ead52cad119 Mon Sep 17 00:00:00 2001 From: Alexey Vazhnov Date: Wed, 22 Oct 2025 18:40:34 +0200 Subject: [PATCH 2/7] Fix typos, improve reStructuredText formatting: inline code blocks, XML code block; "\" wasn't rendered --- docs.rst | 137 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 73 insertions(+), 64 deletions(-) diff --git a/docs.rst b/docs.rst index 20cb549..26b3408 100644 --- a/docs.rst +++ b/docs.rst @@ -1,6 +1,8 @@ Video.database.cleaner documentation ==================================== +.. contents:: + About ----- @@ -32,26 +34,26 @@ has finished it's own cleaning. This cleans the other tables in the database th add-on doesn't touch. It is recommended that this setting is left enabled at all times. -Run clean library 2-6 times -*Kodi will sometimes require multiple passes to clean all the paths that it can potentially clean +* Kodi will sometimes require multiple passes to clean all the paths that it can potentially clean (This is because of "cascading" effects of removing invalid files, invalid paths and invalid parent paths). -When enabled,this option will run Clean Library a number of additonal times, from 2-6, until there are +When enabled, this option will run Clean Library a number of additional times, from 2-6, until there are the same number of paths and files left at the end. D) Back-up local database before cleaning When enabled, the database will be backed up to a sub-directory in Kodi's Database directory. The back-up is time and date stamped in case a user wishes/needs to revert to an older database. -Optionally, it is also possible to specify a name for the back-up. NOTE - It is not possible -for the add-on to back up a MySQL shared database. Users with MySQL databases should use their -tool of choice to manually back-up their database. phpMyAdmin is one such tool used by the authors. +Optionally, it is also possible to specify a name for the back-up. NOTE - It is not possible +for the add-on to back up a MySQL shared database. Users with MySQL databases should use their +tool of choice to manually back-up their database. phpMyAdmin is one such tool used by the authors. E) Show summary window When enabled, a pop-up window will list various settings and paths, depending upon the options chosen in the add-on settings. It is possible to abort the add-on run at this point which will leave the database un-touched, or to select the 'Do It !!' button which will run the cleaning -routine with the chosen settings. If this setting is disabled, the add-on will run without user +routine with the chosen settings. If this setting is disabled, the add-on will run without user intervention although any logs will still be created. Debug and log settings @@ -60,41 +62,41 @@ Debug and log settings A) Log paths to database-cleaner.log If enabled the add-on will create a logfile in Kodi's 'temp' directory that records all the -paths that the add-on will delete. If 'show summary window' is enabled it is possible to stop -the add-on by pressing the 'abort' button. The logfile will still be created so that users can -see what will be deleted before actually doing so. When the add-on cleans the video database, any -existing log will be backed-up to 'database-cleaner.old.log'. +paths that the add-on will delete. If 'show summary window' is enabled it is possible to stop +the add-on by pressing the 'abort' button. The logfile will still be created so that users can +see what will be deleted before actually doing so. When the add-on cleans the video database, any +existing log will be backed-up to ``database-cleaner.old.log``. B) Log creation style -Two options are available - create new log each run or add to log each run. If the first option -is chosen, any existing log will be deleted and replaced with a fresh log. If the second option -is chosen, the logfile will be added to on each run. Logfiles are still backed-up on cleaning, +Two options are available - create new log each run or add to log each run. If the first option +is chosen, any existing log will be deleted and replaced with a fresh log. If the second option +is chosen, the logfile will be added to on each run. Logfiles are still backed-up on cleaning, regardless of this setting. C) Enable debugging to Kodi debug log -In normal use, the add-on writes very little to the Kodi logfile. In the event of an error or an -issue with using this add-on, users should first enable the systemwide Kodi debug log and enable +In normal use, the add-on writes very little to the Kodi logfile. In the event of an error or an +issue with using this add-on, users should first enable the system-wide Kodi debug log and enable this setting to produce a debug log that the authors can use to determine the cause of the error or issue. Sources +++++++ -A) Use sources.xml to determine files to keep +A) Use ``sources.xml`` to determine files to keep -When a user scans a video source into Kodi, the path is stored in a 'sources.xml' file. Enabling +When a user scans a video source into Kodi, the path is stored in a ``sources.xml`` file. Enabling this setting tells the add-on that any files that have been added into the video library by -this method should not be deleted. NOTE - Kodi should delete any files when a user removes a source +this method should not be deleted. NOTE - Kodi should delete any files when a user removes a source but if this has not happened, the add-on will remove them automatically. -B) Use sources.xml on this machine +B) Use ``sources.xml`` on this machine -Generally, this setting should be enabled. Users of MySQL databases do not need to have a 'sources.xml' on each +Generally, this setting should be enabled. Users of MySQL databases do not need to have a ``sources.xml`` on each machine that their database is shared with, because the paths are contained within the shared database. -Such users can disable this setting and can then set the path to a 'sources.xml' on a different networked +Such users can disable this setting and can then set the path to a ``sources.xml`` on a different networked machine. This means MySQL users can run the add-on on any of their machines whilst only having a -'sources.xml' on one machine. +``sources.xml`` on one machine. Advanced ++++++++ @@ -118,31 +120,34 @@ the 'do it !!' button is pressed. C) Replace path in database -If enabled the user must specify an existing path and a new path. Any paths containing the -specified existing path will be renamed to the new path. This is useful if you move a +If enabled, the user must specify an existing path and a new path. Any paths containing the +specified existing path will be renamed to the new path. This is useful if you move a directory on disk but do not want to remove and re-scan the source in Kodi. The add-on -generates the list of paths by appending a wildcard to the supplied 'old path'. This means that -a supplied path of 'nfs://OLD_SERVER' will include 'nfs://OLD_SERVER/Movies' and any other -directories in the tree. If the new path were 'nfs://NEW_SERVER' then every path starting with -'nfs://OLD_SERVER' will become 'nfs://NEW_SERVER' eg with the Movies directory above, the path -would become 'nfs://NEW_SERVER/Movies'. Renaming a path automatically turns off once the path -has been renamed. Again, it is possible by aborting the add-on in the summary window to generate a +generates the list of paths by appending a wildcard to the supplied 'old path'. This means that +a supplied path of ``nfs://OLD_SERVER`` will include ``nfs://OLD_SERVER/Movies`` and any other +directories in the tree. If the new path were ``nfs://NEW_SERVER`` then every path starting with +``nfs://OLD_SERVER`` will become ``nfs://NEW_SERVER`` e.g. with the ``Movies`` directory above, the path +would become ``nfs://NEW_SERVER/Movies``. Renaming a path automatically turns off once the path +has been renamed. Again, it is possible by aborting the add-on in the summary window to generate a logfile showing the original path and the new path to aid users in determining if everything is correct. Clicking on the 'Do it !' button or turning off the summary window will rename the path(s) and turn this setting off. -NOTE - Paths should NOT end with a terminating slash (either '\' or '/' depending on your OS) as this will lead to +NOTE - Paths should NOT end with a terminating slash (either ``\`` or ``/`` depending on your OS) as this will lead to double slashes being inserted into the database. texturecache.py +++++++++++++++ -Inclusion of texturecache.py (by Milhouse): -Additional settings in the Video Database Cleaner addon to allow user to run texturecache.py +Inclusion of ``texturecache.py`` (by Milhouse): + +Additional settings in the Video Database Cleaner addon to allow user to run ``texturecache.py`` after the Video Database Cleaner has completed cleaning the MyMovies.db. + Additional settings allow the user to: -a. Enable or Disable the running of texturecache.py at the end of the Video Database cleanup -b. Configure any of the settings available in the texturecache.cfg file -. If texturecache.py is Enabled, run it, multiple times, each time with one of the following flags: + +a. Enable or Disable the running of ``texturecache.py`` at the end of the Video Database cleanup +b. Configure any of the settings available in the ``texturecache.cfg`` file. +If ``texturecache.py`` is Enabled, run it, multiple times, each time with one of the following flags: [c, C] Automatically cache missing artwork (c), or with option C force the re-caching of existing artwork by removing first then downloading. Can use multiple threads (default is 2) [lc] Same as c and nc, but only considers those media (movies, tvshows/episodes) added since the modification timestamp of the file identified by the property lastrunfile @@ -153,21 +158,25 @@ b. Configure any of the settings available in the texturecache.cfg file [qax] Like the qa option, but performs a remove and then rescan of any media found to fail the QA tests [duplicates] List movies that appear more than once in the media library with the same imdb number -Pipe "texturecache.py output to the database.cleaner logfile will do just that. WARNING: This will create a large file! +Pipe ``texturecache.py`` output to the ``database.cleaner`` logfile will do just that. WARNING: This will create a large file! Deep Clean ++++++++++ -WARNING - CAN BE VERY SLOW! (it will probe every physical file/directory as well as all that are listed in the database) -This option manually scans the locations listed in sources.xml, and builds a list of current, legitimate directories and files. +WARNING - CAN BE VERY SLOW! (it will probe every physical file/directory as well as all that are listed in the database). + +This option manually scans the locations listed in ``sources.xml``, and builds a list of current, legitimate directories and files. It doesn't know or care if directories are removable media/network storage/mount points and ignores the 'keep bookmarks' function and doesn't work on the 'remove specific path' operations (only on the general cleaning operations). -Once it has the list of exisiting, legitimate media files, it will compare this to the database and remove any enries that do not correspond. -*This is helpful when there have been a lot of manualy deleted files/folders that the built in Kodi Video cleaner dos not clean up. -It will help to remove many of the "directory does not exist" erros in the kodi.log file +Once it has the list of existing, legitimate media files, it will compare this to the database and remove any entries that do not correspond. -- Files and Paths only in one directory: - This can help to focus the Deep Clean on a specific directory, instaed of all media. +* This is helpful when there have been a lot of manually deleted files/folders that the built in Kodi Video cleaner dos not clean up. +It will help to remove many of the "directory does not exist" errors in the ``kodi.log`` file + +Settings: + +- Files and Paths only in one directory - this can help to focus the Deep Clean on a specific directory, instead of all media. USAGE @@ -187,36 +196,36 @@ ADVANCED USAGE ============== The add-on can exclude user defined paths (including plugins) from the clean. This is done by -creating a file called 'excludes.xml' in the add-ons 'addon_data' directory. This is located -in Kodi's 'userdata' directory. Inside the addon_data directory, users should find a directory -called 'script.database.cleaner'. NOTE - if you have not changed any settings, this directory +creating a file called ``excludes.xml`` in the add-ons ``addon_data`` directory. This is located +in Kodi's ``userdata`` directory. Inside the addon_data directory, users should find a directory +called ``script.database.cleaner``. NOTE - if you have not changed any settings, this directory may not exist by default. Changing one setting should ensure this directory exists. This file however does not exist by default, it must be created by the user. -The format of the 'excludes.xml' file is simple. EG +The format of the ``excludes.xml`` file is simple. Example: - - plugin://plugin.video.youtube - plugin://plugin.video.itunes_trailers - + .. code-block:: xml + + plugin://plugin.video.youtube + plugin://plugin.video.itunes_trailers + -The excludes.xml file must start with the tag and end with -Any amount of tags can be included. -A wildcard is appended to the contents of any tag, so -plugin:// would exclude ALL plugins -plugin://plugin.video excludes all video plugins +The ``excludes.xml`` file must start with the ```` tag and end with ````. +Any amount of ```` tags can be included. +A wildcard is appended to the contents of any tag, so: -etc etc +- ``plugin://`` would exclude ALL plugins +- ``plugin://plugin.video`` excludes all video plugins +- etc. -Users can be as precise or as vague as they require. EG -plugin://plugin.video.itunes_trailers keeps all the links that -the itunes_trailers plugin has played. Useful if you want to maintain watched status -for your trailers. +Users can be as precise or as vague as they require. Fox example: -plugin://plugin.video.itunes_trailers/trailer/play/http%3A%2F%2Fmovietrailers.apple.com%2Fmovies%2Fdisney%2Fzootopia%2Fzootopia-tlr1_h720p.mov +- ``plugin://plugin.video.itunes_trailers`` keeps all the links that +the ``itunes_trailers`` plugin has played. Useful if you want to maintain watched status +for your trailers. +- ``plugin://plugin.video.itunes_trailers/trailer/play/http%3A%2F%2Fmovietrailers.apple.com%2Fmovies%2Fdisney%2Fzootopia%2Fzootopia-tlr1_h720p.mov`` keeps just that one trailer and deletes all the others. -NOTE - It is possible to specify any valid path or part of a path in the tag +NOTE - It is possible to specify any valid path or part of a path in the ```` tag This allows very fine control over what is removed or kept. - From 0a8917d9120958ddf3eb69007661c52b6865c5c9 Mon Sep 17 00:00:00 2001 From: Alexey Vazhnov Date: Wed, 22 Oct 2025 18:43:36 +0200 Subject: [PATCH 3/7] Render a list as a list instead of big piece of text without newlines; try to fix the last list --- docs.rst | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs.rst b/docs.rst index 26b3408..be5a0d1 100644 --- a/docs.rst +++ b/docs.rst @@ -147,16 +147,17 @@ Additional settings allow the user to: a. Enable or Disable the running of ``texturecache.py`` at the end of the Video Database cleanup b. Configure any of the settings available in the ``texturecache.cfg`` file. + If ``texturecache.py`` is Enabled, run it, multiple times, each time with one of the following flags: -[c, C] Automatically cache missing artwork (c), or with option C force the re-caching of existing artwork by removing first then downloading. Can use multiple threads (default is 2) -[lc] Same as c and nc, but only considers those media (movies, tvshows/episodes) added since the modification timestamp of the file identified by the property lastrunfile -[p, P] Prune texture cache by identifying (p) or removing (P) accumulated cruft such as image previews, previously deleted movies/tv shows/music whose artwork remains in the texture cache even after cleaning the database. Essentially, remove any cached file that is no longer associated with an entry in the media library and is therefore just wasting disk space -[Xd] Remove those rows from the texture cache database that do not have corresponding files in the Thumbnails folder (ie. remove same rows identified by X) -[r, R] Reverse query cache, identifying "orphaned" files that are no longer referenced in the texture cache database. Use R option to auto-delete these files. -[qa] Perform QA check on media library recently added items, identifying missing properties (eg. plot, mpaa certificate, artwork etc.). Default QA period is previous 30 days. Add property qa.file = yes to verify file exists during QA. Add additional QA fields using qa.art.*, qa.blank.* and qa.zero.* properties. -[qax] Like the qa option, but performs a remove and then rescan of any media found to fail the QA tests -[duplicates] List movies that appear more than once in the media library with the same imdb number +- [c, C] Automatically cache missing artwork (c), or with option C force the re-caching of existing artwork by removing first then downloading. Can use multiple threads (default is 2) +- [lc] Same as c and nc, but only considers those media (movies, tvshows/episodes) added since the modification timestamp of the file identified by the property lastrunfile +- [p, P] Prune texture cache by identifying (p) or removing (P) accumulated cruft such as image previews, previously deleted movies/tv shows/music whose artwork remains in the texture cache even after cleaning the database. Essentially, remove any cached file that is no longer associated with an entry in the media library and is therefore just wasting disk space +- [Xd] Remove those rows from the texture cache database that do not have corresponding files in the Thumbnails folder (ie. remove same rows identified by X) +- [r, R] Reverse query cache, identifying "orphaned" files that are no longer referenced in the texture cache database. Use R option to auto-delete these files. +- [qa] Perform QA check on media library recently added items, identifying missing properties (eg. plot, mpaa certificate, artwork etc.). Default QA period is previous 30 days. Add property qa.file = yes to verify file exists during QA. Add additional QA fields using qa.art.*, qa.blank.* and qa.zero.* properties. +- [qax] Like the qa option, but performs a remove and then rescan of any media found to fail the QA tests +- [duplicates] List movies that appear more than once in the media library with the same imdb number Pipe ``texturecache.py`` output to the ``database.cleaner`` logfile will do just that. WARNING: This will create a large file! @@ -220,12 +221,9 @@ A wildcard is appended to the contents of any tag, so: Users can be as precise or as vague as they require. Fox example: -- ``plugin://plugin.video.itunes_trailers`` keeps all the links that -the ``itunes_trailers`` plugin has played. Useful if you want to maintain watched status -for your trailers. -- ``plugin://plugin.video.itunes_trailers/trailer/play/http%3A%2F%2Fmovietrailers.apple.com%2Fmovies%2Fdisney%2Fzootopia%2Fzootopia-tlr1_h720p.mov`` -keeps just that one trailer and deletes all the others. +- ``plugin://plugin.video.itunes_trailers`` - keeps all the links that the ``itunes_trailers`` plugin has played. Useful if you want to maintain watched status for your trailers. +- ``plugin://plugin.video.itunes_trailers/trailer/play/http%3A%2F%2Fmovietrailers.apple.com%2Fmovies%2Fdisney%2Fzootopia%2Fzootopia-tlr1_h720p.mov`` - keeps just that one trailer and deletes all the others. -NOTE - It is possible to specify any valid path or part of a path in the ```` tag +NOTE - It is possible to specify any valid path or part of a path in the ```` tag. This allows very fine control over what is removed or kept. From 22f2e3ec0f13e124015813fb080ca2eaac097fdd Mon Sep 17 00:00:00 2001 From: Alexey Vazhnov Date: Wed, 22 Oct 2025 18:51:47 +0200 Subject: [PATCH 4/7] Improve wording, split to paragraphs to avoid too long text --- docs.rst | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/docs.rst b/docs.rst index be5a0d1..32742e9 100644 --- a/docs.rst +++ b/docs.rst @@ -19,7 +19,7 @@ General settings A) Keep any pvr information -When enabled the add-on will not delete any references to files recorded with a +When enabled, the add-on will not delete any references to files recorded with a live-tv backend. B) Keep bookmarked files @@ -33,8 +33,7 @@ When enabled, the add-on will call Kodi's built in 'clean library' routine after has finished it's own cleaning. This cleans the other tables in the database that the add-on doesn't touch. It is recommended that this setting is left enabled at all times. --Run clean library 2-6 times -* Kodi will sometimes require multiple passes to clean all the paths that it can potentially clean +D) Run clean library 2-6 times - Kodi sometimes requires multiple passes to clean all the paths that it can potentially clean (This is because of "cascading" effects of removing invalid files, invalid paths and invalid parent paths). When enabled, this option will run Clean Library a number of additional times, from 2-6, until there are @@ -44,7 +43,9 @@ D) Back-up local database before cleaning When enabled, the database will be backed up to a sub-directory in Kodi's Database directory. The back-up is time and date stamped in case a user wishes/needs to revert to an older database. -Optionally, it is also possible to specify a name for the back-up. NOTE - It is not possible +Optionally, it is also possible to specify a name for the back-up. + +NOTE - It is not possible for the add-on to back up a MySQL shared database. Users with MySQL databases should use their tool of choice to manually back-up their database. phpMyAdmin is one such tool used by the authors. @@ -69,7 +70,7 @@ existing log will be backed-up to ``database-cleaner.old.log``. B) Log creation style -Two options are available - create new log each run or add to log each run. If the first option +Two options are available - create new log each run or append to existing log each run. If the first option is chosen, any existing log will be deleted and replaced with a fresh log. If the second option is chosen, the logfile will be added to on each run. Logfiles are still backed-up on cleaning, regardless of this setting. @@ -110,8 +111,11 @@ disabled unless the user understands the implications of enabling it. B) Remove specific path from database -If enabled the user must enter a path to be deleted from the database. NOTE - A wildcard will be -appended to the end of the supplied path. The add-on will remove the path from the files table +If enabled the user must enter a path to be deleted from the database. + +NOTE - A wildcard will be appended to the end of the supplied path. + +The add-on will remove the path from the files table in the database. This setting will revert to disabled once the add-on has removed the path from the database. It is however possible, by using the summary window, to generate a logfile showing the details of paths to be removed by aborting the add-on at this point and viewing the log file @@ -123,12 +127,16 @@ C) Replace path in database If enabled, the user must specify an existing path and a new path. Any paths containing the specified existing path will be renamed to the new path. This is useful if you move a directory on disk but do not want to remove and re-scan the source in Kodi. The add-on -generates the list of paths by appending a wildcard to the supplied 'old path'. This means that +generates the list of paths by appending a wildcard to the supplied 'old path'. + +This means that a supplied path of ``nfs://OLD_SERVER`` will include ``nfs://OLD_SERVER/Movies`` and any other directories in the tree. If the new path were ``nfs://NEW_SERVER`` then every path starting with ``nfs://OLD_SERVER`` will become ``nfs://NEW_SERVER`` e.g. with the ``Movies`` directory above, the path would become ``nfs://NEW_SERVER/Movies``. Renaming a path automatically turns off once the path -has been renamed. Again, it is possible by aborting the add-on in the summary window to generate a +has been renamed. + +Again, it is possible by aborting the add-on in the summary window to generate a logfile showing the original path and the new path to aid users in determining if everything is correct. Clicking on the 'Do it !' button or turning off the summary window will rename the path(s) and turn this setting off. From adb7dc9d87e797a6944a03d09a003828e33cbc45 Mon Sep 17 00:00:00 2001 From: Alexey Vazhnov Date: Wed, 22 Oct 2025 18:56:16 +0200 Subject: [PATCH 5/7] texturecache.py: highlight flags in a list --- docs.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs.rst b/docs.rst index 32742e9..ab32f9b 100644 --- a/docs.rst +++ b/docs.rst @@ -158,14 +158,14 @@ b. Configure any of the settings available in the ``texturecache.cfg`` file. If ``texturecache.py`` is Enabled, run it, multiple times, each time with one of the following flags: -- [c, C] Automatically cache missing artwork (c), or with option C force the re-caching of existing artwork by removing first then downloading. Can use multiple threads (default is 2) -- [lc] Same as c and nc, but only considers those media (movies, tvshows/episodes) added since the modification timestamp of the file identified by the property lastrunfile -- [p, P] Prune texture cache by identifying (p) or removing (P) accumulated cruft such as image previews, previously deleted movies/tv shows/music whose artwork remains in the texture cache even after cleaning the database. Essentially, remove any cached file that is no longer associated with an entry in the media library and is therefore just wasting disk space -- [Xd] Remove those rows from the texture cache database that do not have corresponding files in the Thumbnails folder (ie. remove same rows identified by X) -- [r, R] Reverse query cache, identifying "orphaned" files that are no longer referenced in the texture cache database. Use R option to auto-delete these files. -- [qa] Perform QA check on media library recently added items, identifying missing properties (eg. plot, mpaa certificate, artwork etc.). Default QA period is previous 30 days. Add property qa.file = yes to verify file exists during QA. Add additional QA fields using qa.art.*, qa.blank.* and qa.zero.* properties. -- [qax] Like the qa option, but performs a remove and then rescan of any media found to fail the QA tests -- [duplicates] List movies that appear more than once in the media library with the same imdb number +- ``[c, C]`` — automatically cache missing artwork (``c``), or with option ``C`` force the re-caching of existing artwork by removing first then downloading. Can use multiple threads (default is 2). +- ``[lc]`` — same as ``c`` and ``nc``, but only considers those media (movies, tvshows/episodes) added since the modification timestamp of the file identified by the property lastrunfile. +- ``[p, P]`` — prune texture cache by identifying (``p``) or removing (``P``) accumulated cruft such as image previews, previously deleted movies/tv shows/music whose artwork remains in the texture cache even after cleaning the database. Essentially, remove any cached file that is no longer associated with an entry in the media library and is therefore just wasting disk space. +- ``[Xd]`` — remove those rows from the texture cache database that do not have corresponding files in the ``Thumbnails`` folder (ie. remove same rows identified by ``X``). +- ``[r, R]`` — reverse query cache, identifying "orphaned" files that are no longer referenced in the texture cache database. Use ``R`` option to auto-delete these files. +- ``[qa]`` — perform QA check on media library recently added items, identifying missing properties (eg. plot, mpaa certificate, artwork etc.). Default QA period is previous 30 days. Add property ``qa.file = yes`` to verify file exists during QA. Add additional QA fields using ``qa.art.*``, ``qa.blank.*`` and ``qa.zero.*`` properties. +- ``[qax]`` — like the qa option, but performs a remove and then rescan of any media found to fail the QA tests. +- ``[duplicates]`` — list movies that appear more than once in the media library with the same IMDB number. Pipe ``texturecache.py`` output to the ``database.cleaner`` logfile will do just that. WARNING: This will create a large file! From 5efedab88097b37b55e1f1e06c4ac86a66fe84e4 Mon Sep 17 00:00:00 2001 From: Alexey Vazhnov Date: Wed, 22 Oct 2025 18:59:52 +0200 Subject: [PATCH 6/7] Headers: "texturecache.py" and "Deep clean" should not be under "Settings" --- docs.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs.rst b/docs.rst index ab32f9b..50d5953 100644 --- a/docs.rst +++ b/docs.rst @@ -144,7 +144,7 @@ NOTE - Paths should NOT end with a terminating slash (either ``\`` or ``/`` depe double slashes being inserted into the database. texturecache.py -+++++++++++++++ +--------------- Inclusion of ``texturecache.py`` (by Milhouse): @@ -170,8 +170,8 @@ If ``texturecache.py`` is Enabled, run it, multiple times, each time with one of Pipe ``texturecache.py`` output to the ``database.cleaner`` logfile will do just that. WARNING: This will create a large file! -Deep Clean -++++++++++ +Deep clean +---------- WARNING - CAN BE VERY SLOW! (it will probe every physical file/directory as well as all that are listed in the database). From b4c22c367f9be2ab602615b2b04f2663998ab12f Mon Sep 17 00:00:00 2001 From: Alexey Vazhnov Date: Wed, 22 Oct 2025 19:05:10 +0200 Subject: [PATCH 7/7] Advanced usage: very confusing "NOTE", I think the last sentence should not be inside the NOTE. --- docs.rst | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs.rst b/docs.rst index 50d5953..5a958fb 100644 --- a/docs.rst +++ b/docs.rst @@ -17,7 +17,7 @@ Settings General settings ++++++++++++++++ -A) Keep any pvr information +A) Keep any PVR information When enabled, the add-on will not delete any references to files recorded with a live-tv backend. @@ -188,28 +188,31 @@ Settings: - Files and Paths only in one directory - this can help to focus the Deep Clean on a specific directory, instead of all media. -USAGE +Usage ===== To quickly remove any streaming links from your database, turn OFF 'Use sources.xml to determine files to keep' -in the add-on's 'sources' settings. This will remove only streaming links from your database when the add-on is -run. No other cleaning will be done however. +in the add-on's 'sources' settings. This will remove only streaming links from your database when the add-on is +run. No other cleaning will be done however. To run the add-on silently as a scheduled task, turn OFF 'Show summary window' in general settings. To remove old links, streaming info and general rubbish accumulated in the database, ensure that 'use sources.xml to determine files to keep' is turned ON. If you have a PVR backend, turn on -'keep any pvr information' otherwise all information relating to your recordings will be deleted. +'Keep any PVR information' otherwise all information relating to your recordings will be deleted. -ADVANCED USAGE +Advanced usage ============== The add-on can exclude user defined paths (including plugins) from the clean. This is done by creating a file called ``excludes.xml`` in the add-ons ``addon_data`` directory. This is located in Kodi's ``userdata`` directory. Inside the addon_data directory, users should find a directory -called ``script.database.cleaner``. NOTE - if you have not changed any settings, this directory -may not exist by default. Changing one setting should ensure this directory exists. This file -however does not exist by default, it must be created by the user. +called ``script.database.cleaner``. + +NOTE - if you have not changed any settings, this directory +may not exist by default. Changing one setting should ensure this directory exists. + +This file however does not exist by default, it must be created by the user. The format of the ``excludes.xml`` file is simple. Example: