1libinput-record(1)          General Commands Manual         libinput-record(1)
2
3
4

NAME

6       libinput-record - record kernel events
7

SYNOPSIS

9       libinput record [options] [/dev/input/event0 [/dev/input/event1 ...]]
10

DESCRIPTION

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
16       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
18       example, these are valid invocations:
19
20       libinput record /dev/input/event3 touchpad.yml
21
22       libinput record recording.yml
23
24       libinput record --all all-devices.yml
25
26       libinput record /dev/input/event3 /dev/input/event4 tp-and-keyboard.yml
27
28
29       The  events  recorded  are  independent of libinput itself, updating or
30       removing libinput will not change the event stream.
31

OPTIONS

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
35       select the device to record. If unsure, run without any arguments.
36
37       --help  Print help
38
39       --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
45       --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
51       -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
56               device, the first or last argument will be the output file.
57
58       --show-keycodes
59               Show keycodes as-is in the recording. By default,  common  keys
60               are obfuscated and printed as KEY_A to avoid information leaks.
61
62       --with-libinput
63               Record  libinput  events alongside device events.  THIS FEATURE
64               IS EXPERIMENTAL.  See section  RECORDING  LIBINPUT  EVENTS  for
65               more details.
66
67

RECORDING MULTIPLE DEVICES

69       Sometimes  it  is  necessary to record the events from multiple devices
70       simultaneously, e.g.  when an interaction between a touchpad and a key‐
71       board  causes  a  bug. libinput record records multiple devices with an
72       identical time offset, allowing for correct replay of the interaction.
73
74       If multiple devices are recorded, an output filename must be provided.
75
76       All devices to be recorded must be  provided  on  the  commandline,  an
77       example invocation is:
78
79       libinput record -o tap-bug /dev/input/event3 /dev/input/event7
80
81       Note  that  when  recording  multiple devices, only the first device is
82       printed immediately, all other devices and their events are printed  on
83       exit.
84
85

RECORDING LIBINPUT EVENTS

87       When  the  --with-libinput switch is provided, libinput-record initial‐
88       izes a libinput context for the devices  being  recorded.  Events  from
89       these contexts are printed alongside the evdev events.  THIS FEATURE IS
90       EXPERIMENTAL.
91
92       The primary purpose of this feature is debugging and event analysis, no
93       caller may rely on any specific format of the events.
94
95       Note  that  while libinput and libinput-record see the same events from
96       the device nodes, no guarantee can be given about the correct order  of
97       events.  libinput  events  may come in earlier or later than the events
98       from the device nodes and for some  devices,  libinput  may  internally
99       alter the event stream before processing.
100
101       Note  that  the  libinput  context  created by libinput-record does not
102       affect the running desktop session and does not  (can  not!)  copy  any
103       configuration options from that session.
104
105

FILE FORMAT

107       The  output  file format is in YAML and intended to be both human-read‐
108       able and machine-parseable. Below is a short  example  YAML  file,  all
109       keys are detailed further below.
110
111       Any  parsers must ignore keys not specified in the file format descrip‐
112       tion.  The version number field is only used for backwards-incompatible
113       changes.
114
115       version: 1
116       ndevices: 2
117       libinput:
118         version: 1.10.0
119       system:
120         os: "fedora:26"
121         kernel: "4.13.9-200.fc26.x86_64"
122         dmi: "dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:..."
123       devices:
124         - node: /dev/input/event9
125           evdev:
126             # Name: Synaptics TM2668-002
127             # ID: bus 0x1d vendor 0x6cb product 00 version 00
128             # Size in mm: 97x68
129             # Supported Events:
130             # Event type 0 (EV_SYN)
131
132             #.. abbreviated for man page ...
133
134             #
135             name: Synaptics TM2668-002
136             id: [29, 1739, 0, 0]
137             codes:
138               0: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] # EV_SYN
139               1: [272, 325, 328, 330, 333, 334, 335] # EV_KEY
140               3: [0, 1, 24, 47, 48, 49, 52, 53, 54, 55, 57, 58] # EV_ABS
141             absinfo:
142               0: [0, 4089, 0, 0, 42]
143               1: [0, 2811, 0, 0, 41]
144               24: [0, 255, 0, 0, 0]
145               47: [0, 4, 0, 0, 0]
146               48: [0, 15, 0, 0, 0]
147               49: [0, 15, 0, 0, 0]
148               52: [0, 1, 0, 0, 0]
149               53: [0, 4089, 0, 0, 42]
150               54: [0, 2811, 0, 0, 41]
151               55: [0, 2, 0, 0, 0]
152               57: [0, 65535, 0, 0, 0]
153               58: [0, 255, 0, 0, 0]
154             properties: [0, 2, 4]
155           hid: [12, 23, 34, 45, ...]
156           udev:
157             properties:
158             - ID_INPUT_MOUSE=1
159             - ID_INPUT=1
160           quirks:
161             - ModelAppleTouchpad=1
162             - AttrSizeHint=32x32
163           events:
164             - evdev:
165               - [  0,      0,   3,  57,  1420] # EV_ABS / ABS_MT_TRACKING_ID   1420
166               - [  0,      0,   3,  53,  1218] # EV_ABS / ABS_MT_POSITION_X    1218
167               - [  0,      0,   3,  54,  1922] # EV_ABS / ABS_MT_POSITION_Y    1922
168               - [  0,      0,   3,  52,     0] # EV_ABS / ABS_MT_ORIENTATION      0
169               - [  0,      0,   3,  58,    47] # EV_ABS / ABS_MT_PRESSURE        47
170               - [  0,      0,   1, 330,     1] # EV_KEY / BTN_TOUCH               1
171               - [  0,      0,   1, 325,     1] # EV_KEY / BTN_TOOL_FINGER         1
172               - [  0,      0,   3,   0,  1218] # EV_ABS / ABS_X                1218
173               - [  0,      0,   3,   1,  1922] # EV_ABS / ABS_Y                1922
174               - [  0,      0,   3,  24,    47] # EV_ABS / ABS_PRESSURE           47
175               - [  0,      0,   0,   0,     0] # ------------ SYN_REPORT (0) ------- +0ms
176             - evdev:
177               - [  0,  11879,   3,  53,  1330] # EV_ABS / ABS_MT_POSITION_X    1330
178               - [  0,  11879,   3,  54,  1928] # EV_ABS / ABS_MT_POSITION_Y    1928
179               - [  0,  11879,   3,  58,    46] # EV_ABS / ABS_MT_PRESSURE        46
180               - [  0,  11879,   3,   0,  1330] # EV_ABS / ABS_X                1330
181               - [  0,  11879,   3,   1,  1928] # EV_ABS / ABS_Y                1928
182               - [  0,  11879,   3,  24,    46] # EV_ABS / ABS_PRESSURE           46
183               - [  0,  11879,   0,   0,     0] # ------------ SYN_REPORT (0) ------- +0ms
184         # second device (if any)
185         - node: /dev/input/event9
186           evdev: ...
187
188       Top-level  keys  are  listed  below,  see the respective subsection for
189       details on each key.
190
191       version: int
192               The file format version. This version  is  only  increased  for
193               backwards-incompatible  changes.  A  parser must ignore unknown
194               keys to be forwards-compatible.
195
196       ndevices: int
197               The number of device recordings in this file. Always  1  unless
198               recorded with --multiple
199
200       libinput: {...}
201               A dictionary with libinput-specific information.
202
203       system: {...}
204               A dictionary with system information.
205
206       devices: {...}
207               A  list of devices containing the description and and events of
208               each device.
209
210
211   libinput
212       version: string
213               libinput version
214
215
216   system
217       Information about the system
218
219       os: string
220               Distribution ID and version, see os-release(5)
221
222       kernel: string
223               Kernel version, see uname(1)
224
225       dmi: string
226               DMI modalias, see /sys/class/dmi/id/modalias
227
228
229   devices
230       Information about and events from the recorded device nodes
231
232       node: string
233               the device node recorded
234
235       evdev   A dictionary with the evdev device information.
236
237       hid     A list of  integers  representing  the  HID  report  descriptor
238               bytes.
239
240       udev    A dictionary with the udev device information.
241
242       events  A list of dictionaries with the recorded events
243
244   evdev
245       name: string
246               The device name
247
248       id: [bustype, vendor, product, version]
249               The  data  from  the struct input_id, bustype, vendor, product,
250               version.
251
252       codes: {type: [a, b, c ], ...}
253               All evdev types and codes as nested dictionary. The evdev  type
254               is the key, the codes are a list.
255
256       absinfo: {code: [min, max, fuzz, flat, resolution], ...}
257               An  array  of arrays with 6 decimal elements each, denoting the
258               contents of a struct input_absinfo. The first  element  is  the
259               code (e.g. ABS_X) in decimal format.
260
261       properties: [0, 1, ...]
262               Array with all INPUT_PROP_FOO constants. May be an empty array.
263
264   udev
265       properties: list of strings
266               A  list of udev properties in the key=value format. This is not
267               the complete list of properties assigned to the  device  but  a
268               subset  that  is  relevant  to  libinput.  These properties may
269               include properties set on a parent device.
270
271       quirks: list of strings
272               A list of device quirks the key=value format.
273
274
275   events
276       A list of the recorded events. The list contains dictionaries  Informa‐
277       tion  about the events. The content is a list of dictionaries, with the
278       string identifying the type of event sequence.
279
280       { evdev: [ {"data": [sec, usec, type, code, value]}, ...] }
281               Each input_event dictionary contains the contents of  a  struct
282               input_event  in  decimal  format.  The last item in the list is
283               always the SYN_REPORT of this event frame. The next event frame
284               starts a new evdev dictionary entry in the parent events list.
285
286

NOTES

288       This  tool  records events from the kernel and is independent of libin‐
289       put. In other words, updating or otherwise changing libinput  will  not
290       alter the output from this tool. libinput itself does not need to be in
291       use to record events.
292

LIBINPUT

294       Part of the libinput(1) suite
295
296
297
298                                                            libinput-record(1)
Impressum