Proxy Editing

Documentation Documentation - English
1

Introduction

Proxy editing is the process of creating and using low resolution videos and images in places of the original or optimized (Convert to Edit-friendly) files. This provides the advantage that your computer has less work to do in realtime while editing: decoding, scaling, and effects. This is, quite simply, because there are less pixels to compute. Then, when you are ready to export, it will use the original (or optimized) files for full quality.

Performance is optimal when the preview resolution matches the files it is working with. So, this feature is designed to work in conjunction with Preview Scaling. You can still use the proxy mode without Preview Scaling, however, in case something is not working absolutely correct with Preview Scaling.

Proxy editing was added in version 20.06.

The format of a proxy file can be hotly debated because they typically have a number of goals that is difficult to achieve simultaneously: low resolution, small file size, fast to generate, fast to seek and decode, and decent image quality to do understand your work. Not everyone has these goals, but these are Shotcut’s goals, and the format is not configurable. If you do not like how Shotcut generates proxy files, you can still create them with a different process (including Shotcut) if you understand where proxies are stored and how they are named. You are not required to use the MP4 file format for videos, but the name must end with .mp4 for video and .jpg for images. Shotcut can almost always handle a video file whose name does not match the format (but almost never for an image). Fortunately, most people will be happy with JPEG for a proxy image even if not happy with our choice of MP4. A convenience of MP4 is that most media players can play them making it convenient when troubleshooting proxy files.

Settings > Proxy > Use Proxy

This either turns on or off the usage of proxy files for either the current project or the next project you open or start. When you turn this on and open a project, Shotcut looks for proxy files that already exist on your file system and uses them automatically and dynamically. However, it does not automatically
generate a proxy file at this point if there are any missing. Any files added to the Playlist or Timeline will, however, generate a proxy file if one does not exist according to the following rules:

  • It is a video (optionally with audio) or an image file.
  • It is not an image sequence.
  • It does not have an alpha channel (transparency).
  • The video is not only cover art.
  • It does not already have a proxy.
  • Proxy for this file has not been disabled in Properties.
  • Both the image width and image height are more than 1.3X the preview scaling resolution (or 540 if preview scaling is off).
  • A proxy job for this file was not yet created.

It generates a proxy by queuing a job in Jobs. You can continue working with the original at this point. When this proxy job completes, it uses the Replace command to asynchronously update matching clips in Source, Playlist, or Timeline. In doing so, it tries very hard to retain all changes thus far including trimming, filters, and transitions. The vertical resolution of the proxy will be the same as your current Preview Scaling resolution. If Preview Scaling is set to None, then it uses 540p. The width of the proxy will be whatever matches the display aspect ratio for
the target height.

If you turn off proxy with a project opened, Shotcut automatically reopens the project. This causes it to no longer look for proxies during reopen, but it does take time for the project to reload, it clears undo history, and it resets selected clips. It does this without requiring you to save your current project,
however.

If you turn on proxy with a project opened, Shotcut also automatically reopens the project as well while locating whatever proxies are currently available. Then, it prompts if you want to generate proxies for files that do not currently have them subject to the same rules above. These proxy jobs will not do a replace operation as they complete successfully. As the Replace command is still immature, we do not want someone to open a big old project, generate proxies for nearly everything and have it murder your project! Rather, once all of the jobs are done, reopen the project to pick up the proxies.

Settings > Proxy > Storage

Proxy files can be stored in one of two locations: a global folder or a project folder. When opening a project, it looks in both places. The global folder defaults to a sub-folder named “proxies” of your App Data Directory. The project folder is a sub-folder named “proxies” of a project folder created with New
Project > Start on Shotcut’s startup screen.

Choose Settings > Proxy > Storage > Set to change your global project folder to a new location.

Choose Settings > Proxy > Storage > Show to open a folder view from your operating system’s file manager to see which folder is currently in use. This is where newly generated proxies are saved. The result of this action depends on whether you have a project currently opened or started and whether it has a project folder.

Choose Settings > Proxy > Storage > Use Project Folder to control whether you want proxies to be generated in a project folder, if in use, or always in the global folder.

Settings > Proxy > Hardware Encoder

You have the option to use your configured hardware encoder to generate proxies. The lead developer of Shotcut has not found much of an advantage in using it for these low resolution files if you have a strong CPU. Some systems with a weak CPU and compatible GPU may benefit from using it. For most users, do not expect it to significantly improve the speed. Since most hardware encoders tend to create larger files for the same quality as a software encoder, it uses HEVC to keep the file size reasonable. With that said, do not expect them to be much smaller than the software-generated H.264. In fact, they are going to be slower to decode. Still, it is there for your option and experimentation.

Properties

The Properties panel for video clips and images display (PROXY) next to the resolution when it is using a proxy file. You may also notice that Properties shows information about the proxy file instead of the original/converted except for the clip name, duration, frame rate, aspect ratio, and color range. Properties should continue to reflect any overrides where possible.

The Properties panel also has a Proxy menu button with the following options:

  • Make Proxy - forces a proxy to be generated without adhering to the rules above. If you choose not to batch convert a project to proxies, use this to selectively generate proxies. The proxy job this generates will do a replace operation.
  • Delete Proxy - Unfortunately, this is not available on Windows due to file locking prevents it from working (file is likely in use). Otherwise, this does what it says.
  • Disable Proxy - prevents a proxy from being generated for this file. It only applies within the current project and not globally. Also, replaces all matching clips in the project with the original if it using a proxy. Re-enabling does not create or replace with proxy; you need to either reopen the project (if proxy exists) or choose Make Proxy.
  • Copy Hash Code - shows a dialog with a 32 character alpha-numeric code that has also been copied to the system clipboard. This is helpful to track down problems with proxy files or to generate proxy files externally.

Export

Normally when you export, the proxy clips are replaced with their original or converted. However, if you go into Advanced mode and turn on Video > Use preview scaling, not only does export use the preview scaling resolution, but also it uses proxy clips and images to further speed up export! This is intended to more quickly make a rough draft for review, not as a final output, of course.

Known Problems

  1. A proxy can hide a problem with the actual source media, for example, frame accurate seeking on video.

  2. There is no obvious way to add a proxy to a clip-only project. It is by design not to load or create a proxy until you add it to the playlist or timeline since the Source player can be used to quickly preview clips to decide whether to use one. However, it is possible. If you know the proxy already exists, you can save the project and reopen it to pick it up. Otherwise, choose Properties > Proxy > Make Proxy.

  3. File > Export Frame… exports using the proxy up-scaled to project resolution it since uses the current image from the player.

  4. It does not work with File > Open MLT XML As Clip. It does not replace the clips in the sub-project with proxies.

14 Likes
4

Awesome feature. Very useful but I still have a question. My camera already saves a low resolution file for each high resolution file so in some way I already have the proxy files. Is there any way to tell the proxy location so it doesn’t needs to run a job to create it?

5

Yes. Bring into Shotcut’s playlist the original source files. Go to each of those clips’ Properties tab and copy the hash code then paste each of those hash codes as the file names to their corresponding low resolution clips that you will use as proxies for your project. Also, If those low resolution clips files do not end with an “.mp4” file extension then change it to “.mp4” even if it’s not “.mp4”. Finally, make sure all of those low resolution clips are all in the folder you have set as the location for your proxies. After all that, when you go to select Use Proxy, Shotcut should detect your low resolution clips and use them as proxies for your project.

Note that when you select Use Proxy Shotcut will always ask you if you want to make proxies even if you already have proxies made. That message won’t affect Shotcut using the proxies you have already made.

1 Like
6

Is there any way to know the hash code programatically based on the filename or any other attribute of the file? As I already have the proxy files I could write a script to rename all the files automatically without going throught each file in the UI and then renaming the file manually.

7
1 Like
8
4 Likes
9

Why the hash codes for the proxies, makes it quite unreadable?
Would be much simpler to take the original filenames and add a “proxy”?
Would help a lot with easy reuse.

1 Like
10

The hash solves a separate problem: What happens if somebody replaces the original video with a new version and keeps the same file name? The proxy is no longer representative of the new video. A new proxy needs to be made. But how is Shotcut supposed to track whether original videos get swapped and whether a proxy is up-to-date? The hash is the link between the original and the proxy. If the original video changes, the hash of it would change as well. If the hash doesn’t have a matching proxy, then Shotcut knows to generate a new proxy.

To your point, it could maybe be possible to use filenames plus “_proxy” but then use the rule of same date/time stamp to determine if a proxy is up-to-date with the original. But this isn’t as foolproof as a hash.

2 Likes
11

To add to @Austin’s post, the hash code is the specific identity of that very specific file and has nothing to do with whatever the file name is. Think of the hash code like your finger print. You can change your name but you can’t change your finger print. People may not find you if you change your name but if they get a match on your finger prints then they have identified you. Same basic idea works here. So let’s say you made a proxy for a video to use on a project. Then later after that project you change the name of that video and use it on a new separate project. Even though you changed that file’s name, Shotcut will still be able to link that video with the proxy that was made before for the first project thanks to the hash code.

4 Likes
12

Thank you, this makes it clear.
As an advanced computer user it is good practice to add a version number if you tend to change a file or video clip. Normally i would only use raw clips from a camera - this would never be changed. So for my purpose i would still consider it more practical to use file names instead of hash codes, even considering the problem you mentioned. I would guess this holds true for 90+% of all users - maybe i am wrong?

Also, after finishing a project i normally delete all proxies to save space. If i would ever re-use a clip for another movie, i would just have to redo the proxies. But the workflow may be very different from user to user…

13

Considerations:

  1. Let’s say I copied files from my camera card, or downloaded a video from a stock site. Let’s say a power outage happened while copying camera files which left only a partial transfer, or an interrupted download gave me only the first half of my stock video. Let’s say I don’t realize this until I’ve started editing. Many video formats are able to play and convert into proxy despite corruption or missing data in the second half of the video. So, in this situation, I want to re-copy or re-download my videos, but keep the same filename because they literally are the same files, not revisions. How is a proxy built on a corrupt version supposed to know the original changed so it can rebuild itself? A hash will notice it; a filename match will not.

  2. Suppose I am 80% done editing a project, and a long video clip I’ve already placed on the timeline has a lot of noise in it. I could add a “Reduce Noise: Wavelet” filter on the clip, but that filter is super sloooowz and breaks my ability to do quick exports to verify my work. I could turn that filter off until the final export, but that’s one more step I could potentially forget to do, and would cost a lot of time to redo. What I might prefer to do is separately denoise that one clip and replace the original file with the denoised version, including the same filename. This way, I retain all the edits I made against that clip. Had I given it a new name, I would have to drag the new file onto the timeline and cut it up exactly the same way the original version was, which takes time and is extremely error-prone. Or I could edit the .mlt file in a text editor and update the references manually, but this is also tedious and error-prone.

  3. Shotcut allows the project folder to have subfolders. Each subfolder could have sets of files with the same filenames as the other subfolders. An example is time lapse images starting at P0000001.JPG, and each subfolder holds a time lapse sequence for a different date. (Imagine we are building proxies of super-high-resolution images here.) How do we match by filename now? There are duplicate filenames. To match by filename, we also have to capture the entire directory structure to preserve a fully-qualified unique path. Given that Shotcut allows files to be dragged in from outside the project folder, from totally different drive letters and mount points even, there’s no way to represent that level of uniqueness with a filename alone.

  4. Even if #3 were possible, what happens when a user re-arranges media in the project folder? Suppose they had a bunch of items in the playlist and made proxies, but there were too many files to manage. They empty the playlist, sort their videos into subfolders under the project folder, then bring subfolders back into the playlist one at a time. If proxy matches were made by filename using fully-qualified directory structure, nothing would match anymore because the user changed the location of the originals. Shotcut would think “proxies are missing” and rebuild them when this isn’t necessary. All Shotcut needs is a way to link proxies to the correct originals regardless of the location of the original. Hashes can do that.

I’m not saying that filename matching can’t work or be easier in simple scenarios. It can. However, requiring “simple scenarios” is a big caveat.

14

Thanks Austin for your detailed opinion and consideration. Agreed, there are cicumstances where hash codes are preferable. I never was in the situation of one of your 4 points but of course people (including me) could be. In most situations there would be easy workarounds - its more a matter of workflow and comfort. For my (simple) workflow it would just be more comfortable to have readable filenames and i guess that holds true for the big majority of users. To use hash codes is more on the safer side to avoid these problems but on the other hand you have other problems, not knowing what proxies belong to which clips. I end up deleting all proxies after a project and in most cases i would never need them again. Anyway, this is not a big problem either way :slight_smile:

15

I want to generate a proxy for a MLT-as-clip. The properties tab for MLT-as-clips is empty, there is no such thing as the Make Proxy.

16

The option for that workflow I think would be like this:
Export the MLT project in a lossless format (UtVideo for example).
Import that file into the new project.
The proxy will be generated automatically.

17

@ejmillan I wonder if generating the proxies in the MLT before importing it as a clip in the other project would work.

18

It will have to be checked. Oops, wait a minute… now it’s my bedtime. Maybe on the other side of the Atlantic, you’ll be more awake after this time. Good luck with the tests. :grin:

19

Seeing as how Brian added the warning I suggested if anyone tries to export a frame in the middle of proxy mode, is it still necessary to keep this listed under the Known Problems section?

20

@shotcut, can you explain this part of the documentation?

As the Replace command is still immature, we do not want someone to open a big old project, generate proxies for nearly everything and have it murder your project! Rather, once all of the jobs are done, reopen the project to pick up the proxies.

I’m not too clear on this. How can generating proxies for a big old project possibly “murder” that project?

21

Hi, thank you very much for this feature, I was so annoyed from the stuttering when I edit videos and I am happy that this got now added! :slight_smile:
(and I also discovered how overblending a clip works^^, that does really need proxys!).

But now have I a question:
Can I set somewhere that the proxy Clips get auto deletd when I close shotcut? When it crashes it should keep it, but delete them when I close shotcut.
I don’t want to delete them always manually :confused:

I hope I am here correct to ask this, I will wait a few days and then try to ask it somewhere other :smiley:

22

No.

If you want to make it simpler for yourself make sure to set the folder for proxy files in the project folder then when you are done with that specific project you just delete the one project folder and with it the proxy files that are in there.

1 Like