Plays a piece in real time: a process that draws a frame every 1/fps seconds and hands it on.

{:ok, player} = Ascii.Player.start_link(piece: "donut")

receive do
  {:ascii_frame, _ref, frame} -> IO.write(Ascii.Render.ANSI.render(frame))
end

Where frames go

Started with start_link/1 or start/1, a player sends its frames to the process that started it (or :to) as {:ascii_frame, ref, %Ascii.Frame{}}, and stops when that process, its owner, exits. Given a :callback, it calls that instead, in the player's process, and has no owner.

Any process can also subscribe/1 to a player and receive the same messages until it unsubscribes or exits, and frame/1 returns the latest frame. That is how one player serves many viewers:

children = [
  {Ascii.Player, piece: "elixir", name: MyApp.Logo}
]

# in each LiveView
def mount(_params, _session, socket) do
  if connected?(socket), do: Ascii.Player.subscribe(MyApp.Logo)
  {:ok, assign(socket, frame: Ascii.Player.frame(MyApp.Logo))}
end

def handle_info({:ascii_frame, _ref, frame}, socket),
  do: {:noreply, assign(socket, frame: frame)}

Under a supervisor (child_spec/1) a player has no owner unless given :to: it sends nothing to the supervisor, only to its callback and its subscribers. A player with no one to send to holds its frame and does no work, and play time waits with it, until someone subscribes.

Time

Play time advances as upstream's mount advances it: by the real time since the last frame, at most 100 ms a frame, and not at all while paused. Ticks are scheduled against the monotonic clock, so they keep their pace rather than drift by the time each frame takes to draw.

start_link/1 checks the piece and its options, and returns their error if there is one, without starting a process. It returns as soon as the player has started; the player then sets the piece up (a scene takes up to a second, more on a small board) before it does anything else, so a call made meanwhile waits for it. A supervisor starting a scene's player is not held up.

A piece that closes a loop (Ascii.Meta's loop), played with its default options and frame rate, is drawn once a frame of its cycle, as play first reaches each, and then repeated, so after one cycle it costs nothing to play: the frames are kept, up to a megabyte. Frames come at the cycle's places rather than at the exact play time, which is every 1/fps of a second anyway; a frame's t is still the play time.

It needs nothing from Phoenix, so it serves a terminal app (see mix ascii.play) or a device: on Nerves, start it under your own supervisor and draw frame.lines and frame.colors to the display in the callback.

Options

• :piece (required) - a slug or module.
• :to - the owner: the pid to send frames to, which the player stops with. The caller by default, or no one under a supervisor; nil for no one.
• :callback - a function of one frame, instead of messages to an owner.
• :ref - the tag on each message (a fresh reference by default; see ref/1).
• :cache - keep and repeat the frames of a loop (default true).
• :options, :fps, :paper, :color, :ink, :gradient, :parts - as for Ascii.new/2.
• :name - registers the player. Under a supervisor it is also the child's id, so one supervisor can hold several named players.