# `mix ascii.play`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/mix/tasks/ascii.play.ex#L1)

Plays a piece in the terminal, in colour, until you press `q` or Ctrl-C.

    mix ascii.play donut
    mix ascii.play night-coast --fps 10 --mode ansi256
    mix ascii.play typewriter --option "prefix=we make " --option phrases=tools,sites
    mix ascii.play big-text --ink ff5f6d,ffc371
    mix ascii.play boot-log --parts
    mix ascii.play file-tree --part folder=58a6ff --part file.md=d29922
    mix ascii.play MyApp.Pieces.Wave

The piece is a slug or the name of a module implementing `Ascii.Piece`
in this project or its dependencies.

## Options

  * `--fps N` - frames a second (default: the piece's own)
  * `--mono` - draw a coloured piece in one ink
  * `--ink COLOURS` - the colour of a piece drawn in one ink: `rrggbb`
    (a leading `#` is optional, but quote it in a shell), or several,
    comma-separated, for a gradient (see `Ascii.Ink`)
  * `--gradient horizontal|vertical|diagonal` - which way several inks run
    (default `horizontal`)
  * `--parts` - colour the parts of a piece that knows them (see
    `Ascii.Parts`) as it suggests
  * `--part name=COLOUR` - a colour for one part, over `--parts` if given;
    repeat for more
  * `--paper` - dark ink on a light terminal: shaded pieces flip their ramps
  * `--mode truecolor|ansi256|mono` - how colour is written (default
    `truecolor`; use `ansi256` where 24-bit colour is not supported)
  * `--option key=value` - one of the piece's options; repeat for more. Keys
    must be the piece's own (see `Ascii.meta/1`); a list takes
    comma-separated values or JSON.
  * `--seconds S` - stop after S seconds instead of waiting for a key
  * `--interactive` - keys go to a piece that can be used (see
    `Ascii.handle_event/2`): arrows, enter, space, tab, typing. Ctrl-C
    stops it, as `q` would be a key for the piece.

      mix ascii.play file-tree --option walk=false --interactive
      mix ascii.play calendar --option date=2026-10-08 --interactive

After the first frame only the cells that change are written, so it plays
well over SSH or a serial console. The cursor is hidden while it plays and
shown again below the picture, with the colours reset, when it stops.

---

*Consult [api-reference.md](api-reference.md) for complete listing*