Axter-Stash/plugins/RenameFile/README.md

RenameFile: Ver 0.5.0 (By David Maisonave)

RenameFile is a Stash plugin which performs the following tasks.

• Rename Scene File Name (On-The-Fly)
• Append tag names to file name
• Append Performer names to file name

Users can rename the file name by editing the [Title] field and then click [Save].

The [Title] field is located under the [Edit] tab.

Optionally, the plugin can also append tags and performers to the file name if the name does not already exist in the original file name.

Using RenameFile

• Open a scene (via Stash), and click on the [Edit] tab. Populate the [Title] field with the desired file name.
  • Note: Do NOT include the file folder name and do NOT include file extension.
• After populating the Title field, click the save button.
  • Warning: On Windows, if Stash or any other player is playing the video, the RenameFile plugin will get an access denied error if handleExe is not implemented. Use one of the following methods to avoid this error:
    • Option#1: Populate handleExe in renamefile_settings.py with the full path of handle.exe. RenameFile will use this program to close all opened file handles before renaming a file. See options section for more details.
    • Option#2: Refresh the browser for page playing the video before renaming the file via Title field.
• After a few seconds, the file will get renamed and the screen will get updated with the new file name.
• The append tags and performers option is disable by default. To enable these options go to the Settings->Plugins->Plugins->[RenameFile] field options, and enable the associated field.
• When [Append Tags] is enabled, by default tag names are appended to the file name only if the tags do not exist in the original name. Same applies to [Append Performers] option.
• Since this plugin is largely based on the Renamer plugin, it inherited some of its features, like being able to include any of the following fields when auto-renaming is executed:
  • studio, performers, date, height, video_codec, frame_rate
  • To add these fields see the [Key Fields] option in Settings->Plugins->Plugins->[RenameFile].
  • The [Key Fields] can also be used to change the order for the file name format.
• There are many options in Plugins->[RenameFile] UI, and all the options have detailed descriptions. Please advise us if any of the options need further clarification, and provide example details.
  • [Key Fields]: (This option may require more detail than could be provided in the GUI)
    • Define key fields to use to format the file name. This is a comma seperated list, and the list should be in the desired format order. (Default=title,performers,studio,tags)
      • For example, if the user wants the performers name before the title, set the performers name first.
      • Example:"performers,title,tags".
    • This is an example of user adding height:"title,performers,tags,height"
    • Here's an example using all of the supported fields: "title,performers,tags,studio,galleries,resolution,width,height,video_codec,frame_rate,date".
    • The resolution field equals width + height.
    • The date field is not populated by default unless the user explicitly adds the date value to a scene.
    • If [Key Fields] is empty, the default value is used. (Default=title,performers,studio,tags)
• There are additional options in renamefile_settings.py, but these options should only be changed by advanced users, and any changes should be tested first with the [Dry-Run] option enabled.

Note: On Windows 10/11, the file can not be renamed while it's playing. It will result in following error: Error: [WinError 32] The process cannot access the file because it is being used by another process To avoid this error, refresh the URL before changing the Title field.

Requirements

• pip install -r requirements.txt
• Or manually install each requirement:
  • pip install stashapp-tools --upgrade
  • pip install pyYAML
  • pip install requests
• For (Windows-Only) optional feature handleExe, download handle.exe:
  • https://learn.microsoft.com/en-us/sysinternals/downloads/handle

Installation

• Follow Requirements instructions.
• Create a folder named RenameFile, in the stash plugin directory (C:\Users\MyUserName.stash\plugins).
• Download the latest version from the following link: RenameFile, and copy the plugin files to folder.(C:\Users\MyUserName\.stash\plugins\RenameFile).
• Click the [Reload Plugins] button in Stash->Settings->Plugins->Plugins.

That's it!!!

Options

• Main options are accessible in the GUI via Settings->Plugins->Plugins->[RenameFile].
• Advanced options are available in the renamefile_settings.py file. After making changes, go to http://localhost:9999/settings?tab=plugins, and click [Reload Plugins].
  • handleExe - Populate this field in order to allow RenameFile plugin to close all open file handles.
    • In Windows, a file can't be renamed if the file is opened by another process. In other words, if a file is being played by Stash or any other video player, the RenameFile plugin will get an access denied error when trying to rename the file.
    • As a workaround, the 'handleExe' field can be populated with the full path to handle.exe or handle64.exe. (See requirements for download link)
    • RenameFile can use the Handle.exe program to close all opened file handles by all processes before renaming the file.
    • Warning: This feature can cause the process playing the video to crash.

Bugs and Feature Request

Please use the following link to report RenameFile bugs: RenameFile Bug Report

Please use the following link to report RenameFile Feature Request:RenameFile Feature Reques

Please do NOT use the feature request to include any problems associated with errors. Instead use the bug report for error issues.

Note: This script is largely based on the Renamer script.