Ascii.Phoenix.PlayerLive (Ascii v0.3.0)

Copy Markdown View Source

A LiveView that plays one piece, to embed with live_render/3 (or Ascii.Phoenix.player/1). It owns its process and its timer, so the page that embeds it needs no handle_info of its own.

The dead render is frame 0, whole, as HTML, so a page that never connects still shows the picture. Once connected the piece plays one of two ways.

In the browser ("render" => "client", the default)

With the hook in priv/static/ascii_hook.js registered, the browser draws: a text piece in its <pre>, a coloured one on a <canvas>. What the server sends depends on the piece:

  • A piece that closes a loop (see Ascii.loop/1) is drawn for one cycle, in a task, and the cycle is sent once: each frame as the rows cells that changed from the one before, compressed when the browser can inflate it. From then on the browser repeats it and the server does nothing. A cycle over 512 KB as sent is played like any other piece.
  • Any other piece is drawn on the server at its frame rate, and each frame sends the runs of cells that changed, or nothing when none did: a scene, which changes a few cells in a hundred, sends a few kilobytes a frame rather than forty. Play stops while the picture is off screen or its tab hidden.

Readers who prefer reduced motion keep frame 0. Register the hook in your app.js:

import {Ascii} from "../../deps/ascii/priv/static/ascii_hook.js"
let liveSocket = new LiveSocket("/live", Socket, {hooks: {Ascii}, ...})

If no hook answers within two seconds of connecting, the player draws on the server instead.

On the server ("render" => "server")

No JavaScript but LiveView's: the server draws each frame and LiveView patches the <pre> a row at a time, so only the rows that changed are sent, and nothing for a frame that did not change. A loop is drawn once and replayed. The server cannot tell when the picture is out of sight, so it plays on.

Session

Only these keys are read; values may be strings, as from params:

  • "piece" - a slug, or a module implementing Ascii.Piece. A string is always a slug, never read as a module name.
  • "options" - the piece's options, checked against its defaults.
  • "fps" - frames a second, 0 to 60.
  • "mono", "paper" - as for Ascii.new/2.
  • "ink", "gradient" - as for Ascii.new/2: a colour, or several as a list or comma-separated; "horizontal", "vertical" or "diagonal".
  • "parts" - as for Ascii.new/2: a map of part names to colours, or true.
  • "render" - "client" (default) or "server".
  • "label" - what the picture shows, for screen readers. By default the piece tells it from its options (Ascii.describe/1).
  • "interactive" - keys and clicks go to the piece (see Ascii.handle_event/2).
  • "notify" - the LiveView that embeds the player is sent each key and click (see Ascii.Phoenix.player/1).

Only available when phoenix_live_view is a dependency.