V4L2-TRACER(1) User Commands V4L2-TRACER(1)

# [NAME](#NAME)

v4l2-tracer - An application to trace and replay stateless video decoding.

# [SYNOPSIS](#SYNOPSIS)

**v4l2-tracer** \[options] **trace** <*tracee*>

**v4l2-tracer** \[options] **retrace** <*trace\_file*>**.json**

**v4l2-tracer clean** <*file*>**.json**

# [DESCRIPTION](#DESCRIPTION)

The v4l2-tracer utility traces, records and replays userspace applications that implement the v4l2 memory-to-memory stateless video decoder interface.

## [Trace](#Trace)

Trace system calls and video frame data passed by userspace application <*tracee*> to kernel driver. All stateless codec controls in user-space API can be traced. Outputs a JSON-formatted trace file.

## [Retrace](#Retrace)

Read the JSON-formatted <*trace\_file*>**.json**. Replay the same system calls and pass the same video frame data to kernel driver. Outputs a JSON-formatted retrace file.

## [Clean](#Clean)

Remove lines with irrelevant differences (e.g. file descriptors and memory addresses) from JSON files. Outputs a clean copy, not necessarily still in JSON-format.

# [OPTIONS](#OPTIONS)

## [Common Options](#Common_Options)

[**-c**, **--compact**](#c)

Write minimal whitespace in JSON file.

[**-g**, **--debug**](#g)

Turn on verbose reporting plus additional debug info.

[**-h**, **--help**](#h)

Display this message.

[**-r**, **--raw**](#r)

Write decoded video frame data to JSON file.

[**-v**, **--verbose**](#v)

Turn on verbose reporting.

[**-y**, **--yuv**](#y)

Write decoded video frame data to yuv file.

## [Retrace Options](#Retrace_Options)

[**-d**, **--device** <*dev*>](#d)

Use a different video device than specified in the trace file.

<*dev*> must be a digit corresponding to an existing /dev/video<*dev*>

[**-m**, **--media** <*dev*>](#m)

Use a different media device than specified in the trace file.

<*dev*> must be a digit corresponding to an existing /dev/media<*dev*>

# [EXIT STATUS](#EXIT_STATUS)

On success, it returns 0. Otherwise, it will return 1 or an error code.

# [EXAMPLE](#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:](#A)

*71827\_trace.json*

Retrace the trace file:

```
v4l2-tracer retrace 71827_trace.json
    
```

[Specify device nodes if retracing on a different driver:](#Specify)

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

[A retrace file is generated:](#A~2)

*71827\_trace\_retrace.json*

[Remove file descriptors and addresses (optional):](#Remove)

```
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](#BUGS)

Bug reports or questions about this utility should be sent to the linux-media@vger.kernel.org mailinglist.

November 2022 v4l-utils 1.32.0

---

Document: v4l2-tracer(1) from v4l-utils 1.32.0-r1 (Chainguard OS)