Adding upstream version 2.4.0.upstream/2.4.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

2 files changed, 270 insertions, 0 deletions

diff --git a/doc/asciicast-v1.md b/doc/asciicast-v1.md
new file mode 100644
index 0000000..de55223
--- /dev/null
+++ b/doc/asciicast-v1.md
@@ -0,0 +1,64 @@
+# asciicast file format (version 1)
+
+asciicast file is JSON file containing meta-data like duration or title of the
+recording, and the actual content printed to terminal's stdout during
+recording.
+
+Version 1 of the format was used by the asciinema recorder versions 1.0 up to 1.4.
+
+## Attributes
+
+Every asciicast includes the following set of attributes:
+
+* `version` - set to 1,
+* `width` - terminal width (number of columns),
+* `height` - terminal height (number of rows),
+* `duration` - total duration of asciicast as floating point number,
+* `command` - command that was recorded, as given via `-c` option to `rec`,
+* `title` - title of the asciicast, as given via `-t` option to `rec`,
+* `env` - map of environment variables useful for debugging playback problems,
+* `stdout` - array of "frames", see below.
+
+### Frame
+
+Frame represents an event of printing new data to terminal's stdout. It is a 2
+element array containing **delay** and **data**.
+
+**Delay** is the number of seconds that elapsed since the previous frame (or
+since the beginning of the recording in case of the 1st frame) represented as
+a floating point number, with microsecond precision.
+
+**Data** is a string containing the data that was printed to a terminal in a
+given frame. It has to be valid, UTF-8 encoded JSON string as described in
+[JSON RFC section 2.5](http://www.ietf.org/rfc/rfc4627.txt), with all
+non-printable Unicode codepoints encoded as `\uXXXX`.
+
+For example, frame `[5.4321, "foo\rbar\u0007..."]` means there was 5 seconds of
+inactivity between previous printing and printing of `foo\rbar\u0007...`.
+
+## Example asciicast
+
+A very short asciicast may look like this:
+
+    {
+      "version": 1,
+      "width": 80,
+      "height": 24,
+      "duration": 1.515658,
+      "command": "/bin/zsh",
+      "title": "",
+      "env": {
+        "TERM": "xterm-256color",
+        "SHELL": "/bin/zsh"
+      },
+      "stdout": [
+        [
+          0.248848,
+          "\u001b[1;31mHello \u001b[32mWorld!\u001b[0m\n"
+        ],
+        [
+          1.001376,
+          "I am \rThis is on the next line."
+        ]
+      ]
+    }
diff --git a/doc/asciicast-v2.md b/doc/asciicast-v2.md
new file mode 100644
index 0000000..8f1b60a
--- /dev/null
+++ b/doc/asciicast-v2.md
@@ -0,0 +1,206 @@
+# asciicast file format (version 2)
+
+asciicast v2 file is [newline-delimited JSON](http://jsonlines.org/) file where:
+
+* __first line__ contains header (initial terminal size, timestamp and other
+  meta-data), encoded as JSON object,
+* __all following lines__ form an event stream, _each line_ representing a
+  separate event, encoded as 3-element JSON array.
+
+Example file:
+
+```json
+{"version": 2, "width": 80, "height": 24, "timestamp": 1504467315, "title": "Demo", "env": {"TERM": "xterm-256color", "SHELL": "/bin/zsh"}}
+[0.248848, "o", "\u001b[1;31mHello \u001b[32mWorld!\u001b[0m\n"]
+[1.001376, "o", "That was ok\rThis is better."]
+[1.500000, "m", ""]
+[2.143733, "o", "Now... "]
+[4.050000, "r", "80x24"]
+[6.541828, "o", "Bye!"]
+```
+
+Suggested file extension is `.cast`, suggested media type is
+`application/x-asciicast`.
+
+## Header
+
+asciicast header is JSON-encoded object containing recording meta-data.
+
+### Required header attributes:
+
+#### `version`
+
+Must be set to `2`. Integer.
+
+#### `width`
+
+Initial terminal width (number of columns). Integer.
+
+#### `height`
+
+Initial terminal height (number of rows). Integer.
+
+### Optional header attributes:
+
+#### `timestamp`
+
+Unix timestamp of the beginning of the recording session. Integer.
+
+#### `duration`
+
+Duration of the whole recording in seconds (when it's known upfront). Float.
+
+#### `idle_time_limit`
+
+Idle time limit, as given via `-i` option to `asciinema rec`. Float.
+
+This should be used by an asciicast player to reduce all terminal inactivity
+(delays between frames) to maximum of `idle_time_limit` value.
+
+#### `command`
+
+Command that was recorded, as given via `-c` option to `asciinema rec`. String.
+
+#### `title`
+
+Title of the asciicast, as given via `-t` option to `asciinema rec`. String.
+
+#### `env`
+
+Map of captured environment variables. Object (String -> String).
+
+Example env:
+
+```json
+"env": {
+  "SHELL": "/bin/bash",
+  "TERM": "xterm-256color"
+}
+```
+
+> Official asciinema recorder captures only `SHELL` and `TERM` by default. All
+> implementations of asciicast-compatible terminal recorder should not capture
+> any additional environment variables unless explicitly permitted by the user.
+
+#### `theme`
+
+Color theme of the recorded terminal. Object, with the following attributes:
+
+- `fg` - normal text color,
+- `bg` - normal background color,
+- `palette` - list of 8 or 16 colors, separated by colon character.
+
+All colors are in the CSS `#rrggbb` format.
+
+Example theme:
+
+```json
+"theme": {
+  "fg": "#d0d0d0",
+  "bg": "#212121",
+  "palette": "#151515:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#d0d0d0:#505050:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#f5f5f5"
+}
+```
+
+> A specific technique of obtaining the colors from a terminal (using xrdb,
+> requesting them from a terminal via special escape sequences etc) doesn't
+> matter as long as the recorder can save it in the above format.
+
+## Event stream
+
+Each element of the event stream is a 3-tuple encoded as JSON array:
+
+    [time, code, data]
+
+Where:
+
+* `time` (float) - indicates when the event happened, represented as the number
+  of seconds since the beginning of the recording session,
+* `code` (string) - specifies type of event, one of: `"o"`, `"i"`, `"m"`, `"r"`
+* `data` (any) - event specific data, described separately for each event
+  code.
+
+For example, let's look at the following line:
+
+    [1.001376, "o", "Hello world"]
+
+It represents:
+
+* output (code `o`),
+* of text `Hello world`,
+* which happened `1.001376` sec after the start of the recording session.
+
+### Supported event codes
+
+This section describes the event codes supported in asciicast v2 format.
+
+The list is open to extension, and new event codes may be added in both the
+current and future versions of the format. For example, we may add new event
+code for text overlay (subtitles display).
+
+A tool which interprets the event stream (web/cli player, post-processor) should
+ignore (or pass through) event codes it doesn't understand or doesn't care
+about.
+
+#### "o" - output, data written to a terminal
+
+Event of code `"o"` represents printing new data to a terminal.
+
+`data` is a string containing the data that was printed. It must be valid, UTF-8
+encoded JSON string as described in [JSON RFC section
+2.5](http://www.ietf.org/rfc/rfc4627.txt), with any non-printable Unicode
+codepoints encoded as `\uXXXX`.
+
+#### "i" - input, data read from a terminal
+
+Event of code `"i"` represents character typed in by the user, or more
+specifically, raw data sent from a terminal emulator to stdin of the recorded
+program (usually shell).
+
+`data` is a string containing captured ASCII character representing a key, or a
+control character like `"\r"` (enter), `"\u0001"` (ctrl-a), `"\u0003"` (ctrl-c),
+etc. Like with `"o"` event, it's UTF-8 encoded JSON string, with any
+non-printable Unicode codepoints encoded as `\uXXXX`.
+
+> Official asciinema recorder doesn't capture keyboard input by default. All
+> implementations of asciicast-compatible terminal recorder should not capture
+> it either unless explicitly requested by the user.
+
+#### "m" - marker
+
+Event of code `"m"` represents a marker.
+
+When marker is encountered in the event stream and "pause on markers"
+functionality of the player is enabled, the playback should pause, and wait for
+the user to resume.
+
+`data` can be used to annotate a marker. Annotations may be used to e.g.
+show a list of named "chapters".
+
+#### "r" - resize
+
+Event of code `"r"` represents terminal resize.
+
+Those are captured in response to `SIGWINCH` signal.
+
+`data` contains new terminal size (columns + rows) formatted as
+`"{COLS}x{ROWS}"`, e.g. `"80x24"`.
+
+## Notes on compatibility
+
+Version 2 of asciicast file format solves several problems which couldn't be
+easily fixed in the old format:
+
+* minimal memory usage when recording and replaying arbitrarily long sessions -
+  disk space is the only limit,
+* when the recording session is interrupted (computer crash, accidental close of
+  terminal window) you don't lose the whole recording,
+* it's real-time streaming friendly.
+
+Due to file structure change (standard JSON => newline-delimited JSON) version 2
+is not backwards compatible with version 1. Support for v2 has been added in:
+
+* [asciinema terminal recorder](https://github.com/asciinema/asciinema) - 2.0.0
+* [asciinema web player](https://github.com/asciinema/asciinema-player) - 2.6.0
+* [asciinema server](https://github.com/asciinema/asciinema-server) - v20171105
+  tag in git repository