1libinput-record(1) General Commands Manual libinput-record(1)
2
6 libinput-record - record kernel events
7
9 libinput record [options] [/dev/input/event0 [/dev/input/event1 ...]]
10
12 The libinput record tool records kernel events from a device and prints
13 them in a format that can later be replayed with the libinput replay(1)
14 tool. This tool needs to run as root to read from the device.
15 The output of this tool is YAML, see FILE FORMAT for more details. By
17 default it prints to stdout unless an output file is provided. For ex‐
18 ample, these are valid invocations:
19 libinput record /dev/input/event3 touchpad.yml
21 libinput record recording.yml
23 libinput record --all all-devices.yml
25 libinput record /dev/input/event3 /dev/input/event4 tp-and-keyboard.yml
27 The events recorded are independent of libinput itself, updating or re‐
30 moving libinput will not change the event stream.
31
33 If one or more device nodes are given, this tool opens those device
34 nodes. Otherwise, a list of devices is presented and the user can se‐
35 lect the device to record. If unsure, run without any arguments.
36 --help Print help
38 --all Record all /dev/input/event* devices available on the system.
40 This option should be used in exceptional cases only, the out‐
41 put file is almost always too noisy and replaying the recording
42 may not be possible. This option requires --output-file and no
43 device nodes may be provided on the commandline.
44 --autorestart=s
46 Terminate the current recording after s seconds of device inac‐
47 tivity. This option requires that a --output-file is specified.
48 The output filename is used as prefix, suffixed with the date
49 and time of the recording. The timeout must be greater than 0.
50 -o filename.yml
52 --output-file=filename.yml
53 Specifies the output file to use. If --autorestart is given,
54 the filename is used as prefix only. Where --output-file is
55 not given and the first or last argument is not an input de‐
56 vice, the first or last argument will be the output file.
57 --grab Exclusively grab all opened devices. This will prevent events
59 from being delivered to the host system.
60 --show-keycodes
62 Show keycodes as-is in the recording. By default, common keys
63 are obfuscated and printed as KEY_A to avoid information leaks.
64 --with-libinput
66 Record libinput events alongside device events. THIS FEATURE
67 IS EXPERIMENTAL. See section RECORDING LIBINPUT EVENTS for
68 more details.
69 --with-hidraw
71 Record hidraw events alongside device events. DO NOT TYPE SEN‐
72 SITIVE DATA. See RECORDING HID REPORTS for more details.
73
76 Sometimes it is necessary to record the events from multiple devices
77 simultaneously, e.g. when an interaction between a touchpad and a key‐
78 board causes a bug. libinput record records multiple devices with an
79 identical time offset, allowing for correct replay of the interaction.
80 If multiple devices are recorded, an output filename must be provided.
82 All devices to be recorded must be provided on the commandline, an ex‐
84 ample invocation is:
85 libinput record -o tap-bug /dev/input/event3 /dev/input/event7
87 Note that when recording multiple devices, only the first device is
89 printed immediately, all other devices and their events are printed on
90 exit.
91
94 When the --with-libinput commandline option is given, libinput-record
95 initializes a libinput context for the devices being recorded. Events
96 from these contexts are printed alongside the evdev events. THIS FEA‐
97 TURE IS EXPERIMENTAL.
98 The primary purpose of this feature is debugging and event analysis, no
100 caller may rely on any specific format of the events.
101 Note that while libinput and libinput-record see the same events from
103 the device nodes, no guarantee can be given about the correct order of
104 events. libinput events may come in earlier or later than the events
105 from the device nodes and for some devices, libinput may internally al‐
106 ter the event stream before processing.
107 Note that the libinput context created by libinput-record does not af‐
109 fect the running desktop session and does not (can not!) copy any con‐
110 figuration options from that session.
111
114 When the --with-hidraw commandline option is given, libinput-record
115 searches for the hidraw node(s) of the given devices and prints any in‐
116 coming HID reports from those devices.
117 HID reports are not obfuscated and a sufficiently motivated person
119 could recover the key strokes from the logs. Do not type passwords
120 while recording HID reports.
121
124 The output file format is in YAML and intended to be both human-read‐
125 able and machine-parseable. Below is a short example YAML file, all
126 keys are detailed further below.
127 Any parsers must ignore keys not specified in the file format descrip‐
129 tion. The version number field is only used for backwards-incompatible
130 changes.
131 version: 1
133 ndevices: 2
134 libinput:
135 version: 1.10.0
136 system:
137 os: "fedora:26"
138 kernel: "4.13.9-200.fc26.x86_64"
139 dmi: "dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:..."
140 devices:
141 - node: /dev/input/event9
142 evdev:
143 # Name: Synaptics TM2668-002
144 # ID: bus 0x1d vendor 0x6cb product 00 version 00
145 # Size in mm: 97x68
146 # Supported Events:
147 # Event type 0 (EV_SYN)
148 #.. abbreviated for man page ...
150 #
152 name: Synaptics TM2668-002
153 id: [29, 1739, 0, 0]
154 codes:
155 0: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] # EV_SYN
156 1: [272, 325, 328, 330, 333, 334, 335] # EV_KEY
157 3: [0, 1, 24, 47, 48, 49, 52, 53, 54, 55, 57, 58] # EV_ABS
158 absinfo:
159 0: [0, 4089, 0, 0, 42]
160 1: [0, 2811, 0, 0, 41]
161 24: [0, 255, 0, 0, 0]
162 47: [0, 4, 0, 0, 0]
163 48: [0, 15, 0, 0, 0]
164 49: [0, 15, 0, 0, 0]
165 52: [0, 1, 0, 0, 0]
166 53: [0, 4089, 0, 0, 42]
167 54: [0, 2811, 0, 0, 41]
168 55: [0, 2, 0, 0, 0]
169 57: [0, 65535, 0, 0, 0]
170 58: [0, 255, 0, 0, 0]
171 properties: [0, 2, 4]
172 hid: [12, 23, 34, 45, ...]
173 udev:
174 properties:
175 - ID_INPUT_MOUSE=1
176 - ID_INPUT=1
177 quirks:
178 - ModelAppleTouchpad=1
179 - AttrSizeHint=32x32
180 events:
181 - hid:
182 time: [ 0, 0]
183 hidraw0: [1, 2, 3, 4]
184 - evdev:
185 - [ 0, 0, 3, 57, 1420] # EV_ABS / ABS_MT_TRACKING_ID 1420
186 - [ 0, 0, 3, 53, 1218] # EV_ABS / ABS_MT_POSITION_X 1218
187 - [ 0, 0, 3, 54, 1922] # EV_ABS / ABS_MT_POSITION_Y 1922
188 - [ 0, 0, 3, 52, 0] # EV_ABS / ABS_MT_ORIENTATION 0
189 - [ 0, 0, 3, 58, 47] # EV_ABS / ABS_MT_PRESSURE 47
190 - [ 0, 0, 1, 330, 1] # EV_KEY / BTN_TOUCH 1
191 - [ 0, 0, 1, 325, 1] # EV_KEY / BTN_TOOL_FINGER 1
192 - [ 0, 0, 3, 0, 1218] # EV_ABS / ABS_X 1218
193 - [ 0, 0, 3, 1, 1922] # EV_ABS / ABS_Y 1922
194 - [ 0, 0, 3, 24, 47] # EV_ABS / ABS_PRESSURE 47
195 - [ 0, 0, 0, 0, 0] # ------------ SYN_REPORT (0) ------- +0ms
196 - evdev:
197 - [ 0, 11879, 3, 53, 1330] # EV_ABS / ABS_MT_POSITION_X 1330
198 - [ 0, 11879, 3, 54, 1928] # EV_ABS / ABS_MT_POSITION_Y 1928
199 - [ 0, 11879, 3, 58, 46] # EV_ABS / ABS_MT_PRESSURE 46
200 - [ 0, 11879, 3, 0, 1330] # EV_ABS / ABS_X 1330
201 - [ 0, 11879, 3, 1, 1928] # EV_ABS / ABS_Y 1928
202 - [ 0, 11879, 3, 24, 46] # EV_ABS / ABS_PRESSURE 46
203 - [ 0, 11879, 0, 0, 0] # ------------ SYN_REPORT (0) ------- +0ms
204 # second device (if any)
205 - node: /dev/input/event9
206 evdev: ...
207 Top-level keys are listed below, see the respective subsection for de‐
209 tails on each key.
210 version: int
212 The file format version. This version is only increased for
213 backwards-incompatible changes. A parser must ignore unknown
214 keys to be forwards-compatible.
215 ndevices: int
217 The number of device recordings in this file. Always 1 unless
218 recorded with --multiple
219 libinput: {...}
221 A dictionary with libinput-specific information.
222 system: {...}
224 A dictionary with system information.
225 devices: {...}
227 A list of devices containing the description and and events of
228 each device.
229 libinput
232 version: string
233 libinput version
234 system
237 Information about the system
238 os: string
240 Distribution ID and version, see os-release(5)
241 kernel: string
243 Kernel version, see uname(1)
244 dmi: string
246 DMI modalias, see /sys/class/dmi/id/modalias
247 devices
250 Information about and events from the recorded device nodes
251 node: string
253 the device node recorded
254 evdev A dictionary with the evdev device information.
256 hid A list of integers representing the HID report descriptor
258 bytes.
259 udev A dictionary with the udev device information.
261 events A list of dictionaries with the recorded events
263 evdev
265 name: string
266 The device name
267 id: [bustype, vendor, product, version]
269 The data from the struct input_id, bustype, vendor, product,
270 version.
271 codes: {type: [a, b, c ], ...}
273 All evdev types and codes as nested dictionary. The evdev type
274 is the key, the codes are a list.
275 absinfo: {code: [min, max, fuzz, flat, resolution], ...}
277 An array of arrays with 6 decimal elements each, denoting the
278 contents of a struct input_absinfo. The first element is the
279 code (e.g. ABS_X) in decimal format.
280 properties: [0, 1, ...]
282 Array with all INPUT_PROP_FOO constants. May be an empty array.
283 udev
285 properties: list of strings
286 A list of udev properties in the key=value format. This is not
287 the complete list of properties assigned to the device but a
288 subset that is relevant to libinput. These properties may in‐
289 clude properties set on a parent device.
290 quirks: list of strings
292 A list of device quirks the key=value format.
293 events
296 A list of the recorded events. The list contains dictionaries Informa‐
297 tion about the events. The content is a list of dictionaries, with the
298 string identifying the type of event sequence.
299 { evdev: [ [sec, usec, type, code, value], ...] }
301 Each evdev dictionary contains the contents of a struct in‐
302 put_event in decimal format. The last item in the list is al‐
303 ways the SYN_REPORT of this event frame. The next event frame
304 starts a new evdev dictionary entry in the parent events list.
305 { hid: hidrawX : [ 12, 34, 56 ], ...] }
307 The hid dictionary contains the hid reports in decimal format,
308 with the hidraw node as key. The special key time denotes the
309 current time when the report was read from the kernel.
310 Note that the kernel does not provide timestamps for hidraw events and
312 the timestamps provided are from clock_gettime(3). They may be greater
313 than a subsequent evdev event's timestamp.
314
316 This tool records events from the kernel and is independent of libin‐
317 put. In other words, updating or otherwise changing libinput will not
318 alter the output from this tool. libinput itself does not need to be in
319 use to record events.
320
322 Part of the libinput(1) suite
323 libinput-record(1)