V4L2-TRACER(1)

📦
version 1.32.0 · 2 versions
, in alpine 3.24, arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

✨ V4L2-TRACER ✨

okay bestie, so this is v4l2-tracer, a User Commands girlie, and she is An application to trace and replay stateless video decoding. no cap. 💅

🌸 SYNOPSIS 🌸

v4l2-tracer [options] trace <tracee>
v4l2-tracer [options] retrace  <trace_file>.json
v4l2-tracer clean  <file>.json

🦋 DESCRIPTION 🦋

the v4l2-tracer utility is literally out here tracing, recording and replaying userspace applications that implement the v4l2 memory-to-memory stateless video decoder interface. that's the whole vibe. she's the main character of codec debugging. 👑

🎀 Trace

trace system calls and video frame data that the userspace application <tracee> is passing to the kernel driver. All stateless codec controls in the user-space API can be traced. and she outputs a JSON-formatted trace file. periodt. ✨

🎀 Retrace

read the JSON-formatted <trace_file>.json. replay the same system calls and pass the same video frame data to the kernel driver. she outputs a JSON-formatted retrace file. iconic behaviour fr fr. 🫶

🎀 Clean

remove the lines that have irrelevant differences — think file descriptors and memory addresses — from JSON files. outputs a clean copy, which is not necessarily still in JSON-format, so heads up bestie. 💀

💖 OPTIONS 💖

⭐ Common Options

  • -c, --compact — write minimal whitespace in the JSON file. she's on a diet, she's keeping it tight. 🎀
  • -g, --debug — turn on verbose reporting plus additional debug info. more words, more lore. 🔥
  • -h, --help — display this message. your girl always explains herself. 🌈
  • -r, --raw — write decoded video frame data to the JSON file. raw, unfiltered, no makeup. 💅
  • -v, --verbose — turn on verbose reporting. she's a talker, she's a yapper, we love her. 💜
  • -y, --yuv — write decoded video frame data to a yuv file. yuv girl summer. 🌸

⭐ Retrace Options

  • -d, --device <dev> — use a different video device than the one specified in the trace file. <dev> must be a digit corresponding to an existing /dev/video<dev>. not a vibe check you can skip, bestie. ⭐
  • -m, --media <dev> — use a different media device than the one specified in the trace file. <dev> must be a digit corresponding to an existing /dev/media<dev>. same energy, different node. 🦋

✨ EXIT STATUS ✨

on success, it returns 0. otherwise, it will return 1 or an error code. so if you get a 0 you ate, and if you don't… you did not eat. 😭

🌈 EXAMPLE 🌈

trace an application decoding VP8 video:

v4l2-tracer trace gst-launch-1.0 -- filesrc location=test-25fps.vp8 ! parsebin ! v4l2slvp8dec ! videocodectestsink

a trace file is generated:

71827_trace.json

retrace the trace file:

v4l2-tracer retrace 71827_trace.json

specify device nodes if retracing on a different driver:

v4l2-tracer -d0 -m0 retrace 71827_trace.json

a retrace file is generated:

71827_trace_retrace.json

remove file descriptors and addresses (optional):

v4l2-tracer clean 71827_trace.json
v4l2-tracer clean 71827_trace_retrace.json

clean files are generated for comparison:

clean_71827_trace.json
clean_71827_trace_retrace.json

🙈 BUGS 🙈

bug reports or questions about this utility should be sent to the linux-media@vger.kernel.org mailinglist. yes she wants your emails, she wants the tea, she wants the receipts. 📬

ngl bestie, if you found something cursed, do not suffer in silence — the mailinglist is right there. 🫶

that's the whole page, and this cutie ships as v4l-utils 1.32.0, dated November 2022. love that for her. bye bestie, go trace something iconic 💖✨🎀🦋

📦 where this page comes from