Adding recovery menu to OpenShot for recovering previous auto-save files

doc/main_window.rst

@@ -223,6 +223,7 @@ are renamed and/or rearranged.
        - :guilabel:`New Project` Create a blank new project.
        - :guilabel:`Open Project` Open an existing project.
        - :guilabel:`Recent Projects` Access recently opened projects.
+       - :guilabel:`Recovery` Restore a previously saved version of your current project.
        - :guilabel:`Save Project` Save the current project.
        - :guilabel:`Import Files` Import media files into the project.
        - :guilabel:`Choose Profile` Select a project profile (*i.e. 1080p @ 30fps, 720p @ 24fps, ...*).

doc/playback.rst

@@ -74,10 +74,14 @@ multi-threaded CPU, lots of RAM (memory), and a modern GPU. We have listed many
                        the proxy files, simply copy/paste your `*.osp` project file back into the original folder, and export
                        the higher quality, original files.
    Audio Device        If you are still having issues with audio lag or sync, please verify you are using the correct
-                       Audio Device for playback (in the OpenShot Preferences). See :ref:`preferences_preview_ref`. Also,
-                       verify your default audio device (on your operating system) is using the same sample rate. On
-                       certain operating systems (such as Windows), mismatching sample rates can cause severe audio
-                       / video sync problems. Be sure to restart OpenShot after changing the audio device.
+                       :guilabel:`Playback Audio Device` for playback (in the OpenShot Preferences). See :ref:`preferences_preview_ref`. Verify
+                       your default audio device (on your operating system) is using the same sample rate and all *Audio Enhancements* are disabled. On
+                       certain operating systems (such as Windows), mismatching sample rates or audio enhancements can cause severe audio
+                       / video sync problems. Lastly, try adjusting the :guilabel:`Playback Audio Buffer Size` (lower values
+                       will playback audio with less delay, higher values will playback audio with a larger delay). OpenShot
+                       defaults to a buffer size of 512, which is reasonable for most systems, however on some systems you
+                       might need to lower (or raise) this value for smooth and lag-free audio playback. Be sure to restart
+                       OpenShot after changing the audio playback settings.
    ==================  ============
 
 Audio Troubleshooting
@@ -95,10 +99,16 @@ your issue, here are some additional troubleshooting steps you can take.
    Clean Install       See :ref:`preferences_reset_ref` for a clean install
    Audio Device        Check that the Playback Audio Device is set correctly for your sound output under Preferences
                        in the Preview tab. Restart OpenShot after changing the settings. You can also try a different
-                       audio device (USB, audio over HDMI from the video card, etc.) to rule out other audio issues.
+                       audio device (USB, audio over HDMI from the video card, headphones, etc.) to rule out other audio issues.
                        Disable `automatic sound suppression` for voice calls during microphone activity, and disable
                        `Audio Enhancements` under the advanced settings tab of your audio device (not all audio devices
                        have these settings). See :ref:`preferences_preview_ref`.
+   Audio Buffer Size   The audio buffer size is the amount of audio samples which must first be buffered in OpenShot before
+                       audio playback can begin. If this value is too low, you might experience audio break-up / crackle / popping.
+                       If this value is too high, you might experience delays or lag before audio playback begins. OpenShot
+                       defaults this value to 512, which is a reasonable default for most systems, which should provide smooth
+                       audio playback with minimal noticeable lag or delay. However, on some systems this value might need
+                       to be adjusted up or down, for in-sync and lag-free audio playback. The range is 128 to 4096.
    Sample Rate         Ensure that the `Default Audio Sample Rate` and `Default Audio Channels` on the Preview tab of the
                        Preferences window match your hardware. You can also check these settings in the operating system
                        control panel (i.e. Windows Sound Control Panel). See :ref:`preferences_preview_ref`.

doc/preferences.rst

@@ -64,8 +64,6 @@ OpenShot comes with 3 standard themes, which change the look and feel of the pro
 
 .. image:: images/themes.jpg
 
-.. _preferences_preview_ref:
-
 Restoring Defaults
 """"""""""""""""""
 In OpenShot, each preferences category (or tab) in the Preferences window has a **Restore Defaults** button that allows
@@ -84,6 +82,8 @@ to reset certain preferences without affecting others.
 **Tip for Beginners:**
 - If you're not sure about a change you've made in a particular category, don’t hesitate to use the **Restore Defaults** button. It’s a simple way to undo changes and get back to the default settings for that specific category without affecting your overall setup.
 
+.. _preferences_preview_ref:
+
 Preview
 -------
 
@@ -99,7 +99,8 @@ real-time preview audio settings, for example, which audio device and sample rat
    ================================  ==================  ===========
    Setting                           Default             Description
    ================================  ==================  ===========
-   Default Video Profile             HD 720P 30 fps      Select the profile for Preview and Export defaults  
+   Default Video Profile             HD 720P 30 fps      Select the profile for Preview and Export defaults
+   Playback Audio Buffer Size        512                 Adjust how many audio samples must be buffered before audio playback begins. Allowed range of values is 128 to 4096. NOTE: If you are experiencing a large drift or delay in audio playback, try setting this value lower.
    Playback Audio Device             Default             
    Default Audio Sample Rate         44100               
    Default Audio Channels            Stereo (2 Channel)  
@@ -110,21 +111,43 @@ Autosave
 
 .. image:: images/preferences-3-autosave.jpg
 
-Autosave is a saving function in OpenShot which automatically saves the current changes to your project after
+Autosave is a feature in OpenShot which automatically saves the current changes to your project after
 a specific number of minutes, helping to reduce the risk or impact of data loss in case of a crash, freeze
 or user error.
 
+.. table::
+   :widths: 30 15
+
+   =====================================  ==================
+   Setting                                Default
+   =====================================  ==================
+   Enable Autosave                        Enabled
+   Autosave Interval (minutes)            3
+   History Limit (# of undo/redo)         15
+   Recovery Limit (# of project copies)   30
+   =====================================  ==================
+
 Recovery
 """"""""
 
-Before each save, a copy of the current project is created in a recovery folder, to further
+**Before each save**, a compressed ``*.zip`` copy of the current project is saved in the recovery folder, to further
 reduce the risk of data loss. The recovery folder is located at ``~/.openshot_qt/recovery/`` or
-``C:\Users\USERNAME\.openshot_qt\recovery``. If you need to recover a corrupt or broken ``*.osp``
+``C:\Users\USERNAME\.openshot_qt\recovery``.
+
+To recover a corrupt or broken ``*.osp`` project file, use the :guilabel:`File->Recovery`
+menu on the main window after opening your project. If available, a list of matching project versions from
+the recovery folder are listed in chronological order (most recent one at the top). This will
+automatically rename your current project file to ``{project-name}-{time}-backup.osp``, and
+replace it with the recovery project file. You can repeat this process until you find
+the correct recovery project. NOTE: If for some unexpected reason the recovery process fails, you can always rename
+the "-backup.osp" file to the original project file name to restore it.
+
+To **manually** recover a corrupt or broken ``*.osp``
 project file, please find the most recent copy in the recovery folder, and copy/paste the file
-in your original project folder location (i.e. the folder that contains your broken project), and then
-**open** this recovered project file in OpenShot. Many versions of each project are stored in the
-recovery folder, and if you still have issues with the recovered ``*.osp`` file, you can repeat this
-process with older versions contained in the recovery folder.
+into your original project folder location (i.e. the folder that contains your broken project).
+If the recovery file has been zipped (``*.zip``), you must first extract the ``*.osp``, and then
+copy it into your project folder. Recovery files are named ``{time}-{project-name}``. You can also use the
+**Date Modified** on the file to select the version you are interested in recovering.
 
 .. _preferences_cache_ref: