vo_chafa: add a `chafa` VO by StratusFearMe21 · Pull Request #17725 · mpv-player/mpv

StratusFearMe21 · 2026-04-09T01:27:18Z

First off, amazing project. I think MPV has been my default video player for at least 5 years, and it's still definitely the best I've used.

This PR adds a VO that uses the chafa library to render to the terminal. chafa uses a much wider array of symbols than just halfblocks to render graphics, significantly improving the fidelity of it's output over the tct backend. This is meant to be a higher quality alternative to the tct VO for terminals without support for any of the already implemented image protocols (kitty, sixel, etc.).

chafa also supports the iTerm2 image protocol, which isn't currently implemented in any VO, which is a nice bonus.

I initially pointed GLM 4.7 at the sixel VO and told it to replace libsixel with chafa, but I've made sure to throughly review and fix it's output.

github-actions · 2026-04-09T01:49:52Z

Download the artifacts for this pull request:

Windows

macOS

kasper93 · 2026-04-09T11:42:51Z

video/out/vo_chafa.c

+#include <stdio.h>
+#include <stdlib.h>
+
+#include <libswscale/swscale.h>


I don't think we should be including swscale directly, we use our wrappers anyway.

You're right, that header seems to be unused

kasper93 · 2026-04-09T11:45:37Z

DOCS/man/vo.rst


+``chafa``
+    Graphical output for the terminal, using chafa. Tested with ``ghostty`` and
+    ``foot``.


While it's good to note where it was tested in PR, I don't think this information is necessary in the documentation that may outlive any of those claims.

These claims are also present in the docs for the sixel VO. Still removed those from the chafa docs though.

kasper93 · 2026-04-09T11:48:15Z

DOCS/man/vo.rst

+    size both in cells and in pixels. By default it tries to use values which
+    the terminal reports, however, due to differences between terminals this is
+    an error-prone process which cannot be automated with certainty - some
+    terminals report the size in pixels including the padding - e.g. ``xterm``,


e.g. xterm

I don't think xterm, supports chafa. The documentation should be accurate. Is this "terminal size issue" actually a problem on supported terminals, or just copied from sixel documentation?

Please make sure the new added code/docs is accurate and not copy-pasted information.

Should be fixed.

kasper93 · 2026-04-09T11:48:41Z

DOCS/man/vo.rst

+    Additionally, they may behave differently when maximized or in fullscreen,
+    and mpv cannot detect this state using standard methods.
+
+    Sixel size and alignment options:


Not Sixel... But you get the point, this docs needs fixes. I won't point every error, please read through it and fix.

Oops, totally my fault. The docs should be fixed now

kasper93 · 2026-04-09T11:51:21Z

video/out/vo_chafa.c

+#include "video/sws_utils.h"
+#include "video/mp_image.h"
+
+#define IMGFMT IMGFMT_RGB24


Is this the only format supported by the protocol?

Nope, it isn't. Just fixed that

I'm pretty sure the formats with an alpha component are unmultiplied (straight). I could be wrong on that though

kasper93 · 2026-04-09T11:52:31Z

video/out/vo_chafa.c

+};
+
+struct priv {
+    // User specified options


Remove dummy comments, we know that opts are options. I know LLMs likes to spit more tokens that they should have.

Oops, sorry about that. Those have been removed

kasper93 · 2026-04-09T11:57:13Z

video/out/vo_chafa.c

+    }
+
+    if (priv->frame) {
+        talloc_free(priv->frame);


We have TA_FREEP for this.

I get an error when I try to use that in place of talloc_free

assigning to 'struct mp_image' from incompatible type 'void *'

The error is telling you what needs to change. You need one more layer of indirection, TA_FREEP accepts pointer-to-pointer, not the same as regular talloc_free.

kasper93 · 2026-04-09T12:00:44Z

video/out/vo_chafa.c

+    if (priv->opts.width > 0) {
+        // option - set by the user, hard truth
+        total_px_width = priv->opts.width;
+    } else {
+        if (total_px_width <= 0) {
+                // ioctl failed to read terminal width
+                total_px_width = TERMINAL_FALLBACK_PX_WIDTH;
+        } else {
+            if (priv->opts.pad_x >= 0 && priv->opts.pad_x < total_px_width / 2) {
+                // explicit padding set by the user
+                total_px_width -= (2 * priv->opts.pad_x);
+            } else {
+                // rounded "auto padding"
+                total_px_width = total_px_width / num_cols * num_cols;
+            }
+        }
+    }


Is all this needed? Can't you use chafa_canvas_config_get_cell_geometry?

This should be needed. This is where the pad_x and pad_y options are applied

kasper93 · 2026-04-09T12:04:25Z

video/out/vo_chafa.c

+                                   priv->height,
+                                   priv->frame->stride[0]);
+
+    if (mpi)


not needed check

This check is also in the sixel VO on line 458. In the case that frame->current is NULL (when OSD should be redrawn in --force-window --idle mode). mpi is not initialized and remains NULL, and thus can't be freed

kasper93 · 2026-04-09T12:05:51Z

video/out/vo_chafa.c

+    {
+        // Go to the offset row and column
+        gchar pos_buf[64];
+        g_snprintf(pos_buf, sizeof(pos_buf), TERM_ESC_GOTO_YX, priv->top + i , priv->left);


You should use mpv's primitives, like bstr_xappend_asprintf or mp_tprintf if small on stack.

…afa` docs

StratusFearMe21 · 2026-04-09T14:27:35Z

Thanks for the review kasper97, lmk if you need any more changes

…ells of chafa canvas

…mmands

…ly selected by default

…e_chafa_canvas` function

StratusFearMe21 added 4 commits April 8, 2026 15:05

vo_chafa: Initial commit

8735ffd

vo_chafa: Get term_info during preinit

87fc9c1

vo_chafa: set cell geometry on chafa canvas to fix sixel pixel mode

80fbd43

vo_chafa: Create documentation

fe6faf6

StratusFearMe21 and others added 2 commits April 8, 2026 20:46

Merge branch 'master' into vo-chafa

d2abc15

vo_chafa: update defaults to be more sane

c694e2a

StratusFearMe21 changed the title ~~Add a chafa VO~~ vo_chafa: Add a chafa VO Apr 9, 2026

StratusFearMe21 changed the title ~~vo_chafa: Add a chafa VO~~ vo_chafa: add a chafa VO Apr 9, 2026

StratusFearMe21 added 2 commits April 8, 2026 21:45

vo_chafa: get terminfo using default term_db

3f3e1cb

vo_chafa: change dither-mode option to dither for consitency

d0a73b7

kasper93 requested changes Apr 9, 2026

View reviewed changes

StratusFearMe21 added 5 commits April 9, 2026 07:56

vo_chafa: add support for more image formats

1c7670e

vo_chafa: fix comments

debade3

vo_chafa: use mp_tprintf for pos_buf instead of snprintf

22e0f41

vo_chafa: remove header for libswscale

2215e03

DOCS/main/vo.rst: remove explicit mentions of terminals in the `vo_ch…

f9eddc3

…afa` docs

StratusFearMe21 requested a review from kasper93 April 9, 2026 14:19

StratusFearMe21 added 7 commits April 9, 2026 10:19

vo_chafa: use chafa_calc_canvas_geometry to get width and height in c…

629e62d

…ells of chafa canvas

vo_chafa: allow options to change at runtime

b18c6d1

vo_chafa: changing options like this should probably be a separate PR

5ce9e9d

vo_chafa: wrap the graphics rendering code in TERM_ESC_SYNC_UPDATE co…

d62850c

…mmands

vo_chafa: select pixel and canvas mode automatically by default

b19899a

DOCS/man/vo.rst: document that pixel and canvas modes are automatical…

566d888

…ly selected by default

vo_chafa: initialize term_info, pixel, and canvas modes in the `updat…

399170a

…e_chafa_canvas` function

Conversation

StratusFearMe21 commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StratusFearMe21 Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StratusFearMe21 Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StratusFearMe21 Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StratusFearMe21 commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

StratusFearMe21 commented Apr 9, 2026 •

edited

Loading

github-actions bot commented Apr 9, 2026 •

edited

Loading

StratusFearMe21 Apr 9, 2026 •

edited

Loading

StratusFearMe21 Apr 9, 2026 •

edited

Loading

StratusFearMe21 Apr 9, 2026 •

edited

Loading