Jellyfin Plugin: Linked Deletion For Trickplay Folders

Hey everyone! I'm running into a bit of a snag with my Jellyfin setup, and I'm hoping to get some insights or perhaps even a feature request addressed. When I enable the generation of preview thumbnails for Jellyfin and save them alongside my media files, it creates these trickplay folders. These folders are super handy for the progress bar preview, giving that nice visual cue as you scrub through your videos. However, I've noticed a recurring issue: after deleting the main media files, the corresponding trickplay folders don't get removed automatically. This leaves behind empty or orphaned trickplay directories, which isn't a huge deal, but it does clutter up my storage. The error message I'm seeing when trying to clean up scraped files is pretty indicative: 清理刮削文件发生错误：[Errno 21] Is a directory: '/downloads/生活3/影视/Jellyfin/动画TV/仙逆 (2023)/Season 01/仙逆 S01E25 - 1080p 借势.trickplay'. This error essentially tells me that the system is trying to treat the trickplay folder like a file, and of course, it can't delete a directory in that way. It's clear that there's a disconnect in the deletion process. My hope is that the plugin or Jellyfin itself could be updated to support the linked deletion of these trickplay folders whenever the associated media file is removed. This would streamline media management and keep our libraries nice and tidy.

Understanding the Trickplay Folder Functionality

Let's dive a little deeper into what these trickplay folders are all about and why they're generated in the first place. In Jellyfin, when you enable the preview thumbnail generation, the server processes your video files to create a series of small images. These images are then stitched together into a storyboard or a strip that allows users to see a visual representation of the video's content as they hover over or scrub through the timeline. This feature is incredibly useful for quickly finding a specific scene without having to watch large chunks of the video. The trickplay folder is where Jellyfin stores these generated preview images. They are typically located in the same directory as the media file they correspond to, often within a subfolder named .trickplay or simply trickplay. This organization helps keep the metadata close to the media, which is generally a good practice. The generation process itself can be resource-intensive, especially for longer or higher-resolution videos, as it involves decoding the video, extracting frames, and then encoding those frames into a usable preview strip. However, the benefit of enhanced navigation usually outweighs the computational cost for many users. The problem arises when the primary media file is deleted. Jellyfin, or the plugin managing this process, might not have a robust enough mechanism to recognize that the trickplay folder is now orphaned and should also be removed. The error message [Errno 21] Is a directory is a classic sign that the deletion script is encountering a directory when it expects a file, or it's not equipped to handle recursive deletion of directory contents. This suggests that the deletion logic is file-centric rather than considering the associated metadata folders. Ideally, any process that deletes a media file should also check for and delete its corresponding trickplay folder, ensuring a clean removal.

The Current Deletion Issue and Error Analysis

The core of the problem lies in how Jellyfin (or its associated plugins) handles the deletion of media files when trickplay folders are present. As mentioned, when you delete a movie or an episode from your library, the expectation is that all associated metadata, including the preview thumbnail data stored in the trickplay folder, should also be removed. However, the current behavior indicates that this is not happening seamlessly. The error message [Errno 21] Is a directory: '/downloads/生活3/影视/Jellyfin/动画TV/仙逆 (2023)/Season 01/仙逆 S01E25 - 1080p 借势.trickplay' is particularly insightful. In many operating systems and programming contexts, the error Errno 21 often translates to EISDIR, which means "Is a directory." This error typically occurs when a function or command expects to operate on a file (like deleting a file) but is instead given a directory. This suggests that the deletion script is attempting to remove the trickplay folder as if it were a single file, which fails because it's a directory containing multiple files. A proper deletion mechanism for trickplay folders would need to recursively delete the contents of the directory first, and then remove the directory itself. Furthermore, the path in the error message includes .trickplay appended to the filename, which is a bit unusual. Typically, a trickplay folder would be a sibling directory to the media file, or perhaps named something like [MediaFileName].trickplay. The fact that it's appended directly to the media filename in the error might indicate how the plugin is referencing or creating these folders, and consequently, how it's failing to remove them. It's possible that the deletion process is only targeting the original media file and not performing a lookup for associated trickplay data. This oversight leads to the accumulation of these unnecessary directories, which, over time, can consume significant disk space, especially if you have a large media library and frequently add or remove content.

Proposed Solution: Linked Deletion for Trickplay Folders

To address the issue of orphaned trickplay folders, I propose implementing a linked deletion mechanism within Jellyfin or its relevant plugins. This means that when a user initiates the deletion of a media file, the system should automatically detect and remove any associated trickplay folders. The implementation could work in a few ways. Firstly, upon deletion of a media file, the system could search the same directory for a folder with a conventional trickplay naming convention (e.g., a sibling folder named .trickplay or trickplay, or even a folder named after the media file with .trickplay appended). If such a folder is found, the system would then initiate a recursive delete operation for that folder and all its contents. A more robust approach might involve Jellyfin maintaining a more explicit link or metadata entry that associates a media file with its trickplay data. This would allow for a direct lookup and deletion. For instance, when trickplay data is generated, Jellyfin could log the path to the generated folder in its database, tagged with the identifier of the media file. When the media file is deleted, Jellyfin could query this log and remove the corresponding trickplay folder entry and its contents. This linked approach would ensure that no trickplay data is left behind, maintaining a cleaner and more organized media library. It would also prevent the accumulation of disk space due to orphaned folders. This feature would significantly enhance the user experience for those who utilize the preview thumbnail generation, as it removes a manual cleanup step and automates a crucial aspect of media lifecycle management. The benefits are clear: improved storage efficiency, a tidier file system, and a more seamless interaction with Jellyfin's features.

How to Manually Clean Up Trickplay Folders (For Now)

While we wait for a potential built-in solution for linked deletion, there are ways you can manually clean up these trickplay folders. The most straightforward method is to periodically navigate to your media directories and manually delete any trickplay or .trickplay folders you find. Since these are just image caches, deleting them won't harm your media files; Jellyfin will simply regenerate them the next time you access the affected media. If you're comfortable with the command line, you can use commands like find and rm to automate this cleanup across your library. For example, on Linux or macOS, you could navigate to your main media download directory and run a command like this:

find /path/to/your/media -type d -name "trickplay" -exec rm -rf {} + 

Be extremely careful when using rm -rf, as it will forcefully delete directories and their contents without prompting. Always double-check the path you provide to find to ensure you're only targeting the intended trickplay folders and not accidentally deleting other important data. For Windows users, you can achieve a similar result using PowerShell. You might use a command like:

Get-ChildItem -Path "C:\Path\To\Your\Media" -Recurse -Include "trickplay" -Directory | Remove-Item -Recurse -Force

Again, exercise caution with these commands. It's a good idea to first run the Get-ChildItem or find command without the Remove-Item or rm -rf part to see exactly which directories would be targeted before proceeding with the deletion. This manual cleanup is a temporary workaround, but it can help keep your storage tidy until a more integrated solution is available. It's also a good opportunity to ensure that your media organization is as clean as possible, making future management much easier.

User Impact and Community Benefit

Implementing linked deletion for trickplay folders would not only resolve a personal annoyance but also bring significant benefits to the broader Jellyfin community. Many users, especially those with extensive media libraries, are likely encountering this same issue. The accumulation of orphaned trickplay folders can lead to unnecessary disk space consumption, which is a growing concern for many as media files, particularly high-definition content, become larger. Automating the deletion of these cache files ensures that users aren't penalized with wasted storage for using a helpful Jellyfin feature. This improvement enhances the overall user experience by reducing the need for manual intervention and cleanup. It contributes to a more seamless and