Skip to content

Commit

Permalink
Merge pull request OpenShot#5296 from OpenShot/documentation-for-gpt
Browse files Browse the repository at this point in the history 
Improving documentation (Aug 7, 2023)
  • Loading branch information
@jonoomph
jonoomph authored Aug 9, 2023
2 parents f52e744 + 85806c7 commit d982a38
Show file tree
Hide file tree
Showing 13 changed files with 358 additions and 89 deletions.
8 changes: 6 additions & 2 deletions doc/animation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ To adjust the **interpolation mode**, right click on the small graph icon next t

| For more info on creating key frames for location, rotation, scale, shear, and location, see :ref:`clip_transform_ref`.
| For more info on preset animations, see :ref:`clip_presets_ref`.
| For more info on clip properties, see :ref:`clip_properties_ref`.
| For a full list of key frames, see :ref:`clip_properties_ref`.
Bézier Presets
--------------
Expand All @@ -80,10 +80,14 @@ To choose a curve preset, right click on the small graph icon next to a key fram

.. image:: images/curve-presets.jpg

.. _animation_image_seq_ref:

Image Sequences
---------------
If you have a sequence of similarly named images (such as, cat001.png, cat002.png, cat003.png, etc...), you can simply
drag and drop one of them into OpenShot, and you will be prompted to import the entire sequence.
drag and drop one of them into OpenShot, and you will be prompted to import the entire sequence. OpenShot will playback
these sequential images rapidly, as if they are frames in a video. The rate or speed in which these images are displayed
is based on their frame rate.

.. image:: images/import-image-sequence.jpg

Expand Down
116 changes: 67 additions & 49 deletions doc/clips.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,25 @@ Key frames are automatically created at the current playback position, to help c

For more info on key frames and animation, see :ref:`animation_ref`.

Time Re-mapping
---------------
Adjusting the speed and direction of a clip can be achieved using the :guilabel:`Time` property. You can
use one of the available presets (`normal, fast, slow, freeze, freeze & zoom, forward, backward`), by right clicking
on a Clip and choosing the :guilabel:`Time` menu. Many common presets are available in this menu, for reversing,
speeding up, and slowing down a video clip.

Optionally, you can manually set key-frame values for the :guilabel:`Time` property. The value represents the
`frame number` at the position of the key-frame. This can be tricky to determine and might require a calculator to find
the needed values. For example, if the beginning of your Clip sets a time value of ``300`` (i.e. `frame 300`),
and the end of your clip sets a time value of ``1`` (`frame 1`), OpenShot will play this clip backwards, starting
at frame 300 and ending at frame 1, at the appropriate speed (based on where these key-frames are set on the timeline).
NOTE: To determine the total number of frames in a clip, multiply the duration of the file with the FPS of the project (for
example: ``47.0 sec clip duration X 24.0 Project FPS = 1128 total frames``).

This allows for some very complex scenarios, such as jump cutting inside a clip, reversing a portion of a clip,
slowing down a portion of a clip, freezing on a frame, and much more. See :ref:`animation_ref` for more
details on manual key-frame animations.

Effects
-------
In addition to the many clip properties which can be animated and adjusted, you can also drop an effect directly onto
Expand All @@ -141,56 +160,53 @@ effect, and allow you to edit (and animate) them. For the full list of effects,

.. _clip_properties_ref:

Properties
----------
Clip Properties
---------------
Below is a list of clip properties which can be edited, and in most cases, animated over time. To view a clip's properties,
right click and choose **Properties**. The property editor will appear, where you can change these properties. Note: Pay
close attention to where the play-head (i.e. red playback line) is. Key frames are automatically created at the current playback
position, to help create animations.

.. table::
:widths: 24 60

====================== ============
Name Description
====================== ============
Alpha Curve representing the alpha (1 to 0)
Channel Filter A number representing an audio channel to filter (clears all other channels)
Channel Mapping A number representing an audio channel to output (only works when filtering a channel)
Frame Number The format to display the frame number (if any)
Duration The length of the clip (in seconds)
End The end trimming position of the clip (in seconds)
Gravity The gravity of a clip determines where it snaps to its parent (details below)
Enable Audio An optional override to determine if this clip has audio (-1=undefined, 0=no, 1=yes)
Enable Video An optional override to determine if this clip has video (-1=undefined, 0=no, 1=yes)
ID A randomly generated GUID (globally unique identifier) assigned to each clip
Track The layer which holds the clip (higher tracks are rendered on top of lower tracks)
Location X Curve representing the relative X position in percent based on the gravity (-1 to 1)
Location Y Curve representing the relative Y position in percent based on the gravity (-1 to 1)
Volume Mixing The volume mixing choices control how volume is adjusted before mixing (None=don't adjust volume of this clip, Reduce=lower the volume to 80%, Average=divide volume based on # of concurrent clips, details below)
Origin X Curve representing the rotation origin point, X position in percent (-1 to 1)
Origin Y Curve representing the rotation origin point, Y position in percent (-1 to 1)
Parent The parent object to this clip, which makes many of these keyframe values initialize to the parent value
Position The position of the clip on the timeline (in seconds, 0.0 is the beginning of the timeline)
Rotation Curve representing the rotation (0 to 360)
Scale The scale determines how a clip should be resized to fit its parent (details below)
Scale X Curve representing the horizontal scaling in percent (0 to 1)
Scale Y Curve representing the vertical scaling in percent (0 to 1)
Shear X Curve representing X shear angle in degrees (-45.0=left, 45.0=right)
Shear Y Curve representing Y shear angle in degrees (-45.0=down, 45.0=up)
Start The start trimming position of the clip (in seconds)
Time Curve representing the frames over time to play (used for speed and direction of video)
Volume Curve representing the volume (0 to 1)
Wave Color Curve representing the color of the audio wave form
Waveform Should a waveform be used instead of the clip's image
====================== ============

Details
:widths: 18 18 70

====================== ========== ============
Name Type Description
====================== ========== ============
Alpha Key-Frame Curve representing the alpha (1 to 0)
Channel Filter Key-Frame A number representing an audio channel to filter (clears all other channels)
Channel Mapping Key-Frame A number representing an audio channel to output (only works when filtering a channel)
Frame Number Enum The format to display the frame number (if any)
Duration Float The length of the clip (in seconds)
End Float The end trimming position of the clip (in seconds)
Gravity Enum The gravity of a clip determines where it snaps to its parent (details below)
Enable Audio Enum An optional override to determine if this clip has audio (-1=undefined, 0=no, 1=yes)
Enable Video Enum An optional override to determine if this clip has video (-1=undefined, 0=no, 1=yes)
ID String A randomly generated GUID (globally unique identifier) assigned to each clip
Track Int The layer which holds the clip (higher tracks are rendered on top of lower tracks)
Location X Key-Frame Curve representing the relative X position in percent based on the gravity (-1 to 1)
Location Y Key-Frame Curve representing the relative Y position in percent based on the gravity (-1 to 1)
Volume Mixing Enum The volume mixing choices control how volume is adjusted before mixing (None=don't adjust volume of this clip, Reduce=lower the volume to 80%, Average=divide volume based on # of concurrent clips, details below)
Origin X Key-Frame Curve representing the rotation origin point, X position in percent (-1 to 1)
Origin Y Key-Frame Curve representing the rotation origin point, Y position in percent (-1 to 1)
Parent String The parent object to this clip, which makes many of these keyframe values initialize to the parent value
Position Float The position of the clip on the timeline (in seconds, 0.0 is the beginning of the timeline)
Rotation Key-Frame Curve representing the rotation (0 to 360)
Scale Enum The scale determines how a clip should be resized to fit its parent (details below)
Scale X Key-Frame Curve representing the horizontal scaling in percent (0 to 1)
Scale Y Key-Frame Curve representing the vertical scaling in percent (0 to 1)
Shear X Key-Frame Curve representing X shear angle in degrees (-45.0=left, 45.0=right)
Shear Y Key-Frame Curve representing Y shear angle in degrees (-45.0=down, 45.0=up)
Start Float The start trimming position of the clip (in seconds)
Time Key-Frame Curve representing the frames over time to play (used for speed and direction of video)
Volume Key-Frame Curve representing the volume (0 to 1)
Wave Color Key-Frame Curve representing the color of the audio wave form
Waveform Bool Should a waveform be used instead of the clip's image
====================== ========== ============

Gravity
"""""""

**Gravity**:

Gravity sets an initial position for the clip, once it has been scaled as above. The options are:
Gravity sets an initial position for the clip, once it has been scaled as above. The options are:

- *Top Left* – the top and left edges of the clip align with the top and left edges of the screen
- *Top Center* – the top edge of the clip aligns with the top edge of the screen; the clip is horizontally centered on the screen.
Expand All @@ -202,24 +218,26 @@ Details
- *Bottom Center* – the bottom edge of the clip aligns with the bottom edge of the screen; the clip is horizontally centered on the screen.
- Bottom Right – the bottom and right edges of the clip align with the bottom and right edges of the screen

**Scale**:

This is the initial resizing method, which may be further adjusted by Scale X and Scale Y (below). The options are:
Scale
"""""
This is the initial resizing method, which may be further adjusted by Scale X and Scale Y (below). The options are:

- *Best Fit* (default) – the clip is as large as possible without changing the aspect ratio.
- *Crop* – the aspect ratio of the clip is maintained while the clip is enlarged to fill the entire screen, even if that means some of it will be cropped.
- *None* – the clip is its original size.
- *Stretch* – the clip is stretched to fill the entire screen, changing the aspect ratio if necessary.

**Volume Mixing**:
.. _clip_volume_mixing_ref:

Mixing audio involves adjusting volume levels so that they maintain a good range within each clip, and then adjusting them in proportion to other clips used in the project. The following values are available:
Volume Mixing
"""""""""""""
Mixing audio involves adjusting volume levels so that they maintain a good range within each clip, and then adjusting them in proportion to other clips used in the project. The following values are available:

- **None** - Make no adjustments to volume data before mixing audio
- **Average** - Automatically divide the volume of each clip based on the # of overlapping clips. For example, 2 overlapping clips would each have 50% volume.
- **Reduce** - Automatically reduce the clip's volume by 20%, allowing it to mix with other clips, and reducing the likelihood of over-volume loud events.

Consider the following guidelines when adjusting volume levels:
Consider the following guidelines when adjusting volume levels:

- If you combine particularly loud audio clips on multiple tracks, clipping (a staccato distortion) may occur. To avoid clipping, reduce volume levels.
- If you need to adjust the volume separately in different parts of a clip (for example, one person’s voice is faint, while later another’s is too loud), you can use keyframes to vary the volume throughout the clip.
Expand Down
2 changes: 2 additions & 0 deletions doc/files.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,8 @@ all files you need to add, right click, and choose Add to Timeline.
6 Transitions Choose a specific transition to use between files, random, or none
== ================== ============

.. _file_properties_ref:

Properties
----------
To view the properties of any imported file in your video project, right click on the file, and choose **File Properties**.
Expand Down
26 changes: 11 additions & 15 deletions doc/getting_started.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@
dedicated to delivering high quality video editing and animation solutions
to the world.
.. OpenShot Video Editor is free software: you can redistribute it and/or
modify it under the terms of the GNU General Public License as published by
.. OpenShot Video Editor is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
Expand All @@ -17,8 +17,6 @@
.. You should have received a copy of the GNU General Public License
along with OpenShot Library. If not, see <http://www.gnu.org/licenses/>.
.. Edited September 25, 2020 - [USA]TechDude
Video Editing Basics
====================

Expand All @@ -33,22 +31,21 @@ makes the whole process much more manageable.

There are three main jobs of video editing:

1. Remove mistakes or unwanted sections
2. Keep the video moving at an engaging pace
3. Insert supporting footage, audio, or titles
#. Remove mistakes or unwanted sections
#. Keep the video moving at an engaging pace
#. Insert supporting footage, audio, or titles

Use these three points as a checklist as you edit.

Computer
--------
Video editing does not require an expensive machine, especially if you are a
beginner. It would be best if you had a decent monitor and graphics card. If
beginner. However, it would be best if you had a more recent monitor and graphics card. If
you have an older computer, check your system specifications against OpenShot's
:ref:`min_system_req_ref` to make sure it works for video editing.
Unfortunately, many older computers are not fast enough for video editing, and you
should upgrade your whole system, if possible.


Accessories
-----------
Before beginning a video project, ensure there is enough storage space on your
Expand All @@ -68,7 +65,6 @@ Becoming a great video editor isn’t effortless, but with practice and patience
you’ll be editing like a professional in no time. Here are a few of the
essential tips and techniques you need to know to become a skilled video editor.


#. Pick the Right Computer
While having a great computer won’t necessarily make you a great video
editor, a faster computer will allow you to focus more of your time on the
Expand All @@ -77,11 +73,11 @@ essential tips and techniques you need to know to become a skilled video editor.
depends on your own preferences.

#. Keep Shooting
Record more video that you think you will need for your project. Include
Record more video and audio than you think you will need for your project. Include
video that enhances the scene, sets a mood, or tells a story. You can use
the extra video for smooth transitions in your project. If you are
comfortable using multiple devices, use two devices simultaneously the
insert video from either device into your project.
the extra video for smooth transitions in your project. If your project requires
voice overs or narration, we suggest using an external application to record
your microphone (since OpenShot does not include any recording capabilities yet).

#. Organize Your Project Files
Composition is the key to success, whether you are running Linux, on a Mac,
Expand All @@ -91,7 +87,7 @@ essential tips and techniques you need to know to become a skilled video editor.
but if you move them after your project is saved, you could lose your
entire project. Organizing before you begin editing can be very
advantageous.

#. Watch Everything
Watching everything is the first step in the editing process. Writer and
filmmaker David Andrew Stoler says there is gold in the most unlikely of
Expand Down
8 changes: 3 additions & 5 deletions doc/glossary.rst
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
.. Copyright (c) 2008-2020 OpenShot Studios, LLC
.. Copyright (c) 2008-2016 OpenShot Studios, LLC
(http://www.openshotstudios.com). This file is part of
OpenShot Video Editor (http://www.openshot.org), an open-source project
dedicated to delivering high quality video editing and animation solutions
to the world.
.. OpenShot Video Editor is free software: you can redistribute it and/or
modify it under the terms of the GNU General Public License as published by
.. OpenShot Video Editor is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
Expand All @@ -17,8 +17,6 @@
.. You should have received a copy of the GNU General Public License
along with OpenShot Library. If not, see <http://www.gnu.org/licenses/>.
.. Edited September 26, 2020 - [USA]TechDude
.. _glossary_ref:

Glossary
Expand Down
1 change: 1 addition & 0 deletions doc/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ Table of Contents:
profiles
import_export
preferences
playback
developers
contributing
learn_more
Expand Down
Loading

0 comments on commit d982a38

Please sign in to comment.