shotcut Documentation

Technical Documentation: mltframework/shotcut

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

Shotcut - a free, open source, cross-platform **video editor**

• Features: https://www.shotcut.org/features/
• Roadmap: https://www.shotcut.org/roadmap/

Install Copy Chapter

Binaries are regularly built and are available at https://www.shotcut.org/download/.

Contributors Copy Chapter

• Dan Dennedy <http://www.dennedy.org> : main author
• Brian Matherly <[email protected]> : contributor

Dependencies Copy Chapter

Shotcut's direct (linked or hard runtime) dependencies are:

• MLT: multimedia authoring framework
• Qt 6 (6.4 minimum): application and UI framework
• FFTW
• FFmpeg: multimedia format and codec libraries
• Frei0r: video plugins
• SDL: cross-platform audio playback

See https://shotcut.org/credits/ for a more complete list including indirect
and bundled dependencies.

License Copy Chapter

GPLv3. See COPYING.

How to build Copy Chapter

Warning: building Shotcut should only be reserved to beta testers or contributors who know what they are doing.

Qt Creator Copy Section

The fastest way to build and try Shotcut development version is through Qt Creator.

From command line Copy Section

First, check dependencies are satisfied and various paths are correctly set to find different libraries and include files (Qt, MLT, frei0r and so forth).

Configure

In a new directory in which to make the build (separate from the source):

cmake -DCMAKE_INSTALL_PREFIX=/usr/local/ /path/to/shotcut

We recommend using the Ninja generator by adding -GNinja to the above command line.

Build

cmake --build .

Install

If you do not install, Shotcut may fail when you run it because it cannot locate its QML
files that it reads at run-time.

cmake --install .

Translation Copy Chapter

If you want to translate Shotcut to another language, please use Transifex.

Drmingw Doc README (`drmingw/doc/README.md`) Copy Section

Dr. Mingw

About Copy Chapter

Dr. Mingw is a Just-in-Time (JIT) debugger. When the application throws an unhandled exception, Dr. Mingw attaches itself to the application and collects information about the exception, using the available debugging information.

Dr. Mingw can read debugging information in DWARF format — generated by the Gnu C/C++ Compiler, and in a PDB file — generated by the Microsoft Visual C++ Compiler. It relies upon the DbgHelp library to resolve symbols in modules compiled by the Microsoft tools.

The functionality to resolve symbols and dump stack backtraces is provided as DLLs so it can be embedded on your applications/tools.

Download Copy Chapter

• Releases.

• Git repository.

Installation Copy Chapter

You should download and install the 64 bits binaries for Windows 64 bits (and it will handle both 64 and 32 bits applications), or the 32 bits versions for Windows 32 bits.

To install enter

drmingw -i

Dr. Mingw will register itself as the JIT debugger by writting into the system registry. Make sure you have Administrator rights. See this page for more information on how this works.

If the installation is sucessful, the following message box should appear:

To enable other options they must be set them allong with the -i option. For example,

drmingw -i -v

Usage Copy Chapter

You can easily try Dr. Mingw by building and running the included sample. Depending of your Windows version, you'll see a familiar dialog:

If you request to debug the program, Dr. Mingw will attach to the faulting application, collect information about the exception, and display the dialog

To resolve the addresses it's necessary to compile the application with debugging information. In case of address is in a DLL with no debugging information, it will resolve to the precedent exported symbol.

Command Line Options Copy Chapter

The following table describes the Dr. Mingw command-line options. All comand-line options are case-sensitive.

MgwHelp Copy Chapter

The MgwHelp library aims to be a drop-in replacement for the DbgHelp library, that understand MinGW symbols. It provides the same interface as DbgHelp library, but it is able to read the debug information produced by MinGW compilers/linkers.

MgwHelp is used by Dr.MinGW and ExcHndl below to lookup symbols.

But the hope is that it will eventually be used by third-party Windows development tools (like debuggers, profilers, etc.) to easily resolve symbol on binaries produced by the MinGW toolchain.

MgwHelp relies on libdwarf to read DWARF debugging information.

NOTE: It's still work in progress, and only exports a limited number of symbols. So it's not a complete solution yet

ExcHndl Copy Chapter

The exchndl.dll is a embeddable exception handler. It produces the similar output to Dr. Mingw, but it can be bundled into your applications. The exception handling routine runs in the same process context of the faulting application.

If you deploy ExcHndl together your own programs you can have almost the same exception information that you would get with Dr. Mingw, but with no need for the end user to install Dr. Mingw installed.

Usage Copy Section

You can use ExcHndl by:

• including exchndl.dll, mgwhelp.dll, dbghelp.dll, symsrv.dll, and symsrv.yes with your application binaries

• pass -lexchndl to GNU LD when linking your program

• call ExcHndlInit() from your main program

• you can also override the report location by invoking the exported ExcHndlSetLogFileNameA entry-point.

You can also use ExcHndl by merely calling LoadLibraryA("exchndl.dll") for historical reasons, but that's no longer recommended.

Example Copy Section

The sample sample.exe application uses the second method above. Copy all DLLs mentioned above to the executable directory. When you run it, even before general protection fault dialog box appears, it's written to the sample.RPT file a report of the fault.

Here is how sample.RPT should look like:

-------------------

Error occured on Tuesday, June 25, 2013 at 08:18:51.

z:\projects\drmingw\sample\sample.exe caused an Access Violation at location 74D2ECC0 in module C:\Windows\syswow64\msvcrt.dll Writing to location 00000001.

Registers:
eax=00003039 ebx=00000064 ecx=00000001 edx=0028fe50 esi=00003039 edi=0000006f
eip=74d2ecc0 esp=0028fc5c ebp=0028fe30 iopl=0         nv up ei pl nz na pe nc
cs=0023  ss=002b  ds=002b  es=002b  fs=0053  gs=002b             efl=00010202

AddrPC   Params
74D2ECC0 0028FE50 00403064 00000000  msvcrt.dll!_strxfrm_l
74D2EDC8 74D2E991 00403064 00000000  msvcrt.dll!sscanf
74D2ED67 00403067 00403064 00000001  msvcrt.dll!sscanf
004013DE 00000008 60000000 40166666  sample.exe!Function  [z:\projects\drmingw\sample/sample.cpp @ 12]
00401D3E 00000004 40B33333 0028FF08  sample.exe!Class::StaticMethod(int, float)  [z:\projects\drmingw\sample/sample.cpp @ 17]
00401D5E 00401970 00714458 0000000C  sample.exe!Class::Method()  [z:\projects\drmingw\sample/sample.cpp @ 21]
004013F9 00000001 00572F38 00571B38  sample.exe!main  [z:\projects\drmingw\sample/sample.cpp @ 27]
004010FD 7EFDE000 F769D382 00000000  sample.exe
77269F42 00401280 7EFDE000 00000000  ntdll.dll!RtlInitializeExceptionChain
77269F15 00401280 7EFDE000 00000000  ntdll.dll!RtlInitializeExceptionChain

Frequently Asked Questions Copy Chapter

Why do I get a different stack trace from your example? Copy Section

Make sure you don't use Dr.Mingw and exchndl at the same time -- the latter seems to interfere with the former by some obscure reason.

Which options should I pass to gcc when compiling? Copy Section

This options are essential to produce suitable results are:

• -g : produce debugging information

• -fno-omit-frame-pointer : use the frame pointer (frame pointer usage is disabled by default in some architectures like x86_64 and for some optimization levels; and it may be impossible to walk the call stack without it)

You can choose more detailed debug info, e.g., -g3, -ggdb. But so far I have seen no evidence this will lead to better results, at least as far as Dr.MinGW is concerned.

Why are the reported source lines always after the call? Copy Section

Callers put the return IP address on the stack. Therefore the source lines we get when looking the address is not the line of the call, but instead the line of the instruction immediately succeeding the call.

Where should I put the `*.PDB` files? Copy Section

Dr. Mingw uses DbgHelp to handle .PDB files so it has the same behavior.

If you test on the machine you built, you typically need to do nothing. Otherwise you'll need to tell where your .PDBs are through the _NT_SYMBOL_PATH environment variable.

How can I get a stack trace from a process that is hung? Copy Section

drmingw -b -p 12345

or

drmingw -b -p application.exe

Links Copy Chapter

Related tools Copy Section

• binutil's addr2line (included in MinGW)
• cv2pdb - DWARF to PDB converter
• google-breakpad
• CrashRpt
• dbg

Suggested Reading Copy Section

• A Crash Course on the Depths of Win32 Structured Exception Handling, MSJ January 1997
• MSJEXHND - Part 1, Under the Hood, MSJ April 1997
• MSJEXHND - Part 2, Under the Hood, MSJ May 1997
• Bugslayer, MSJ, August 1998
• The Win32 Debugging Application Programming Interface
• Using the Windows debugging API on Windows 64
• About Exceptions and Exception Handling
• Microsoft PDB format

--- METRICS ---

• Files Extracted: 2
• Estimated Token Budget: ~2996 tokens
• Canonical Reference: https://codewiki.google/github.com/mltframework/shotcut