1.. _desktop_notifications: 2 3 4Desktop notifications 5======================= 6 7|kitty| implements an extensible escape code (OSC 99) to show desktop 8notifications. It is easy to use from shell scripts and fully extensible to 9show title and body. Clicking on the notification can optionally focus the 10window it came from, and/or send an escape code back to the application running 11in that window. 12 13The design of the escape code is partially based on the discussion in 14the defunct 15`terminal-wg <https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/13>`_ 16 17The escape code has the form:: 18 19 <OSC> 99 ; metadata ; payload <terminator> 20 21Here ``<OSC>`` is :code:`<ESC>]` and ``<terminator>`` is 22:code:`<ESC><backslash>`. The metadata is a section of colon separated 23:code:`key=value` pairs. Every key must be a single character from the set 24:code:`a-zA-Z` and every value must be a word consisting of characters from 25the set :code:`a-zA-Z0-9-_/\+.,(){}[]*&^%$#@!`~`. The payload must be 26interpreted based on the metadata section. The two semi-colons *must* always be 27present even when no metadata is present. 28 29Before going into details, lets see how one can display a simple, single line 30notification from a shell script:: 31 32 printf '\x1b]99;;Hello world\x1b\\' 33 34To show a message with a title and a body:: 35 36 printf '\x1b]99;i=1:d=0;Hello world\x1b\\' 37 printf '\x1b]99;i=1:d=1:p=body;This is cool\x1b\\' 38 39The most important key in the metadata is the ``p`` key, it controls how the 40payload is interpreted. A value of ``title`` means the payload is setting the 41title for the notification. A value of ``body`` means it is setting the body, 42and so on, see the table below for full details. 43 44The design of the escape code is fundamentally chunked, this is because 45different terminal emulators have different limits on how large a single escape 46code can be. Chunking is accomplished by the ``i`` and ``d`` keys. The ``i`` 47key is the *notification id* which can be any string containing the characters 48``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and 49can only take the values ``0`` and ``1``. A value of ``0`` means the 50notification is not yet done and the terminal emulator should hold off 51displaying it. A value of ``1`` means the notification is done, and should be 52displayed. You can specify the title or body multiple times and the terminal 53emulator will concatenate them, thereby allowing arbitrarily long text 54(terminal emulators are free to impose a sensible limit to avoid 55Denial-of-Service attacks). 56 57Both the ``title`` and ``body`` payloads must be either UTF-8 encoded plain 58text with no embedded escape codes, or UTF-8 text that is base64 encoded, in 59which case there must be an ``e=1`` key in the metadata to indicate the payload 60is base64 encoded. 61 62When the user clicks the notification, a couple of things can happen, the 63terminal emulator can focus the window from which the notification came, and/or 64it can send back an escape code to the application indicating the notification 65was activated. This is controlled by the ``a`` key which takes a comma 66separated set of values, ``report`` and ``focus``. The value ``focus`` means 67focus the window from which the notification was issued and is the default. 68``report`` means send an escape code back to the application. The format of the 69returned escape code is:: 70 71 <OSC> 99 ; i=identifier ; <terminator> 72 73The value of ``identifier`` comes from the ``i`` key in the escape code sent by 74the application. If the application sends no identifier, then the terminal 75*must* use ``i=0``. Actions can be preceded by a negative sign to turn them 76off, so for example if you do not want any action, turn off the default 77``focus`` action with:: 78 79 a=-focus 80 81Complete specification of all the metadata keys is in the table below. If a 82terminal emulator encounters a key in the metadata it does not understand, 83the key *must* be ignored, to allow for future extensibility of this escape 84code. Similarly if values for known keys are unknown, the terminal emulator 85*should* either ignore the entire escape code or perform a best guess effort 86to display it based on what it does understand. 87 88.. note:: 89 It is possible to extend this escape code to allow specifying an icon for 90 the notification, however, given that some platforms, such as macOS, dont 91 allow displaying custom icons on a notification, at all, it was decided to 92 leave it out of the spec for the time being. 93 94 Similarly, features such as scheduled notifications could be added in future 95 revisions. 96 97 98======= ==================== ========= ================= 99Key Value Default Description 100======= ==================== ========= ================= 101``a`` Comma separated list ``focus`` What action to perform when the 102 of ``report``, notification is clicked 103 ``focus``, with 104 optional leading 105 ``-`` 106 107``d`` ``0`` or ``1`` ``1`` Indicates if the notification is 108 complete or not. 109 110``e`` ``0`` or ``1`` ``0`` If set to ``1`` means the payload is base64 encoded UTF-8, 111 otherwise it is plain UTF-8 text with no C0 control codes in it 112 113``i`` ``[a-zA-Z0-9-_+.]`` ``0`` Identifier for the notification 114 115``p`` One of ``title`` or ``title`` Whether the payload is the notification title or body. If a 116 ``body``. notification has no title, the body will be used as title. 117======= ==================== ========= ================= 118 119 120.. note:: 121 |kitty| also supports the legacy OSC 9 protocol developed by iTerm2 for 122 desktop notifications. 123