Skip to content

Latest commit

 

History

History
116 lines (98 loc) · 4.89 KB

REPORTING-BUGS.md

File metadata and controls

116 lines (98 loc) · 4.89 KB
Raw

Reporting bugs

There are couple of ways to report a problem:

  • you can use GitHub issues for reporting bugs. You need to register, but it is only matter of filling username and password.
  • alternativey you can use our an e-mail conference ultragrid-dev _at_ cesnet.cz which leads to developers of UltraGrid
  • if not sure if the problem is a bug, you can also use GitHub discussions to ask a question.

Please try to follow these rules when reporting a bug if possible:

  1. test the issue with latest version of UltraGrid (either release or continuous channel), preferably using our official binary builds

  2. if relevant, attach information about your environment (SW/HW)

  3. report a minimal broken example demonstrating the problem -- this mainly means removing irrelevant parameters from UltraGrid command-line. Explicit parameters' specification like video mode or similar properties is however encouraged.

  4. if the problem is specific to some device, try to use either testcard to generate the signal that isn't displayed correctly or GL/SDL display to display the broken signal, recommended reported use-cases:

    uv -t testcard:codec=RGB -d ndi # problems with NDI display
# problems with DeckLink cap. (`-d gl` can be omitted eg. for a crash)
uv -t decklink[:args] -d gl
uv -t testcard -c libavcodec:encoder=libx264 -d gl # compression problem

    not recommended:

    # not sure what the signal actually is and if probiem is in cap. or disp
uv -t decklink[:args] -d decklink[:args]
# not run on localhost; use only to report network problems
uv -t testcard -c libavcodec[:params] receiver
# bloated
uv -t testcard -c libavcodec -m 1400 -l 30M -T 32
# using developer-only parameters
uv [params] --param xyz=val

    If testcard isn't capable to produce a signal, that is complex enough to demonstrate the problem, you can try following videos to vidcap file (-t file:<filename>):

    1. filesamples.com
    2. Ultra Video Group Dataset
    3. archive.org, eg. Elephants Dream, Sintel, BloodSpell or Big Buck Bunny

Following hints are rather to be considered if you consider it relevant. It also doesn't necessarily need to be present in the first bug report but requested by developers:

  1. If you suspect that the issue may not be always replicable, you can use a script ultragrid-bugreport-collect.sh to collect data about a computer and attach its result (Linux/macOS).

  2. If the problem is a crash (segmentation fault, abort), if possible, attach a core dump (if generated) and the binary (if you compiled by yourself, otherwise the executable version). If core dump is not generated, a backtrace (see below) might have been generated to standard error output so please attach this. Also the terminal output containg the error context would be helpful.

Decoding stacktrace (Linux)

If reporting a bug, you can also decode the stacktrace for the bug report. The following is intended mainly for advanced users with UltraGrid compiled from source, don't bother with it not sure. Requires addr2line and objdump.

Eg. we have a stacktrace saved as stacktrace.txt:

Backtrace:
./bin/uv(+0x21b946)[0x562ebedee946]
/lib/x86_64-linux-gnu/libc.so.6(+0x41950)[0x7f7d9dfe4950]
/lib/x86_64-linux-gnu/libc.so.6(gsignal+0xcb)[0x7f7d9dfe48cb]
/lib/x86_64-linux-gnu/libc.so.6(abort+0x116)[0x7f7d9dfc9864]
./bin/uv(main+0x2b93)[0x562ebedf7141]
/lib/x86_64-linux-gnu/libc.so.6(__libc_start_main+0xf2)[0x7f7d9dfcbcb2]
./bin/uv(_start+0x2e)[0x562ebecd7b9e]

In UltraGrid sources there is a script tools/stacktrace_addr2line.sh. You can use that to decode the stacktrace addresses to human-readable symbols:

$ ./tools/stacktrace_addr2line.sh < stacktrace.txt
Decoding ../build-devel-linux/bin/uv(+0x21b946)[0x563cded2e946]
crash_signal_handler(int)
/home/martin/Projects/ultragrid/build-devel-linux/../src/main.cpp:301
Decoding /lib/x86_64-linux-gnu/libc.so.6(+0x41950)[0x7fc826d85950]
killpg
??:?
Decoding /lib/x86_64-linux-gnu/libc.so.6(gsignal+0xcb)[0x7fc826d858cb]
??
??:0
Decoding /lib/x86_64-linux-gnu/libc.so.6(abort+0x116)[0x7fc826d6a864]
??
??:0
Decoding ../build-devel-linux/bin/uv(main+0x2b93)[0x563cded37141]
main
/home/martin/Projects/ultragrid/build-devel-linux/../src/main.cpp:1313
Decoding /lib/x86_64-linux-gnu/libc.so.6(__libc_start_main+0xf2)[0x7fc826d6ccb2]
??
??:0
Decoding ../build-devel-linux/bin/uv(_start+0x2e)[0x563cdec17b9e]
_start
??:?

Note: The script needs to be called from the same directory as UltraGrid was called for the script to be able to find the executable.