Proxy Editing

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. 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.

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

  3. The video filter Crop: Source does not work as expected because it does not know about proxy and simply delete N rows or columns of pixels from its input. The only workarounds are to disable proxy on the clip where it is used or turn off proxy mode, adjust as needed, turn on proxy mode, and ignore the incorrect preview. Fixed in version 20.09.13, but you need to select each instance of the filter at least once to make it convert to a new parameters format.

  4. The video filter Rotate and Scale X and Y offset parameters do not work as expected. Fixed in version 20.09.13 by merging Rotate into Size and Position. Existing filters in old projects are not converted. You need to replace the old Rotate and Scale (now hidden in filter menu) with the new Size, Position & Rotate filter.

5 Likes

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?

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.

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.