Live streaming protocol

[Barre]

Hi,

I saw that in the latest release there is "added experimental websocket-based live streaming protocol (ALiS)". Is there any documentation showing what a rough implementation would look like in terms of messages?

[ku1ik]

Hey @Barre, good catch :) There's no docs yet, but I'll be working on documentation for this in the coming weeks. I plan to move all docs from https://asciinema.org/docs to https://docs.asciinema.org and then add streaming doc there. I can ping you when it's up, if you'd like.

[ku1ik]

In short: player's websocket driver supports 3 types of live protocols:

• raw - binary output sent as binary websocket messages,
• ALiS (asciinema live stream) - simple binary protocol, similar to asciicast format, but encoded as short binary websocket messages,
• JSON - asciicast compatible protocol, where events are JSON encoded text websocket messages

The player automatically detects which one the server uses so there's not much to configure on the player side other than specifying wss://host/path URL as source argument to create function.

To test this you can do the following:

Create named pipe:

mkfifo live.pipe

Start websocket server with websocat, which reads from the pipe:

websocat -v --text --no-close ws-l:127.0.0.1:9002 reuse-raw:autoreconnect:readfile:live.pipe

Connect to the server in JS like this:

AsciinemaPlayer.create('ws://127.0.0.1:9002');

Then in another shell start recording session:

asciinema rec live.pipe

[Barre]

Thank you @ku1ik! I will explore this :)

To provide some context on my situation:

I've been utilizing xterm.js in conjunction with a custom websocket protocol to navigate a recorded terminal session and to view both live sessions and their history. I'm considering switching to asciinema, believing it might be more suitable given its design for recordings and the extensive tools it offers.

[ku1ik]

Cool! If you go for it let me know, curious to hear how it goes.

[Barre]

Will do!

[Barre]

@ku1ik, I want to extend my thanks for your efforts. I've successfully integrated asciinema in place of xterm.js in my tool, and the process proceeded exceptionally well. However, I encountered an issue with the resizing of the terminal window. This problem persists even when sending the asiicast header at the commencement of the stream (using websocket.js).

I observed that you have pushed the following commits:

• asciinema/asciinema-player@c20cd5c
• asciinema/asciinema@a9dc2e5

I will proceed to implement the 'r' event on my end.

I guess I'm lucky :) Thanks again.

[ku1ik]

Glad to hear. Yeah, sending the header object mid-stream doesn't work, it's meant to for the initial setup of the recording. Resize events (r) are the way to go. I haven't released this on npmjs.org to the latest tag yet, but if you'd like to try it out you can use RC version, [email protected], in your package.json.

[Barre]

After some experimentation, everything ran smoothly! I managed to replace xterm.js + my solution without much trouble.

Currently, it seems there isn't support for seeking previous data. Given that I'm not dealing with vast amounts of data, the websocket server could theoretically stream all the data from the beginning to attain the current state. Ideally, I'd like to integrate both live and past recorded data within the same user interface, such as the way youtube or twitch is doing it without hacking too much into asciinema itself.

[ku1ik]

Current impl of websocket driver doesn't support seeking indeed, and it would require heavy modification, or some sort of merging it with the recording driver. I don't think this will happen soon, maybe eventually (depends on how big of a deal this will be for people).

On related note, websocket driver supports buffering, correctly handling events with "future" timestamps. See here https://github.com/orgs/asciinema/discussions/214#discussioncomment-5803453 . Not sure if you useful to you though.

[Barre]

Regardless, even if websocket.js did support streaming, there would still be a user interface challenge concerning the resumption of "live data". I've decided to proceed with asciinema, but I'll manage the transition between the "past" and "live" portions of an ongoing session externally. This approach might be more logical in any case.

Thank you so much for your insights! :)

[ku1ik]

Right, there's many challenges around making the experience youtube/twitch-like and I don't want to go there, yet :) I'm glad you like asciinema and got it working good enough for your project 🎉

[ku1ik]

FYI with the release of asciinema CLI 3.0 the streaming protocol(s) have been solidified and properly documented here: https://docs.asciinema.org/manual/server/streaming/