{"id":13429805,"url":"https://github.com/hzeller/timg","last_synced_at":"2025-05-14T06:13:50.283Z","repository":{"id":41406375,"uuid":"61416223","full_name":"hzeller/timg","owner":"hzeller","description":"A terminal image and video viewer.","archived":false,"fork":false,"pushed_at":"2025-05-11T10:19:25.000Z","size":3117,"stargazers_count":2191,"open_issues_count":27,"forks_count":78,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-05-11T11:20:08.190Z","etag":null,"topics":["ascii-art","gif","image","image-viewer","imagemagick","iterm2","jpeg","kitty","kitty-terminal","png","sixel","sixel-graphics","terminal","terminal-based","terminal-graphics","unicode-art","xterm"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hzeller.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-06-18T04:06:23.000Z","updated_at":"2025-05-11T10:19:20.000Z","dependencies_parsed_at":"2024-04-23T05:10:02.147Z","dependency_job_id":"b5a6a190-fb21-4172-8a63-dc08acf7bd33","html_url":"https://github.com/hzeller/timg","commit_stats":{"total_commits":513,"total_committers":16,"mean_commits":32.0625,"dds":0.06822612085769986,"last_synced_commit":"e1e3dad5e6946dffc4ca317adf39e1034339bdcb"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hzeller%2Ftimg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hzeller%2Ftimg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hzeller%2Ftimg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hzeller%2Ftimg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hzeller","download_url":"https://codeload.github.com/hzeller/timg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253562359,"owners_count":21927880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ascii-art","gif","image","image-viewer","imagemagick","iterm2","jpeg","kitty","kitty-terminal","png","sixel","sixel-graphics","terminal","terminal-based","terminal-graphics","unicode-art","xterm"],"created_at":"2024-07-31T02:00:45.770Z","updated_at":"2025-05-14T06:13:50.220Z","avatar_url":"https://github.com/hzeller.png","language":"C++","funding_links":[],"categories":["C++","\u003ca name=\"cpp\"\u003e\u003c/a\u003eC++","Terminal","terminal","Tools","\u003ca name=\"viewers\"\u003e\u003c/a\u003eViewers","Table of Contents","Media \u0026 Entertainment","CLI Applications"],"sub_categories":["Apps and Tools","C++"],"readme":"\u003cimg src=\"img/logo.svg\" align=\"left\" width=\"165\" alt=\"timg logo\" title=\"timg\"\u003e\n\u003c!-- github markdown eats style, otherwise we could use em-units for width. --\u003e\n\nTerminal Image and Video Viewer\n===============================\n\n[![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://github.com/hzeller/timg/blob/main/LICENSE) \u0026nbsp;\n[![Ubuntu Build](../../workflows/CI/badge.svg)](../../actions/workflows/ubuntu.yml)\n[![macOS Build](../../workflows/macOS%20Build/badge.svg)](../../actions/workflows/macos.yml)\n[![macOS Brew Building HEAD](../../workflows/macOS%20Brew%20Building%20HEAD/badge.svg)](../../actions/workflows/macos-brew.yml)\n\n\n### https://timg.sh/\n\nA user-friendly terminal image viewer that uses graphic capabilities of\nterminals (Sixel, Kitty or iterm2), or 24-Bit color capabilities and unicode\ncharacter blocks if these are not available.\n\nOn terminals that implement the [sixel] protocol, the\n[Kitty Graphics Protocol], or the [iTerm2 Graphics Protocol] this displays\nimages in full resolution.\n\nBut even the fallback block display is usable.\n![](./img/sunflower-term.png)\n\nDisplays regular images, plays animated gifs, scrolls static images and\nplays videos.\n\nUseful if you want to have a quick visual check without leaving the comfort\nof your shell and having to start a bulky image viewer. Sometimes this is the\nonly way if your terminal is connected remotely via ssh. And of course if you\ndon't need the resolution. While icons typically fit pixel-perfect, larger\nimages are scaled down to match the resolution.\n\nThe command line accepts any number of image/video filenames that it shows\nin sequence one per page or in a grid in multiple columns, depending on your\nchoice of `--grid`. The output is emitted in-line with minimally messing\nwith your terminal, so you can simply go back in history using your terminals'\nscroll-bar (Or redirecting the output to a file allows you to later\nsimply `cat` that file to your terminal. Even `less -R` seems to be happy with\nit).\n\n#### Pixelation\nOn a regular terminal, block-characters are used to output images. Half blocks\npresent pixels color-accurately, and quarter blocks provide a higher spatial\nresolution at the expense of slightly worse color accuracy. These modes should\nbe compatible with most common terminals that support UTF8 and 24Bit color.\n\nIf you are on a [Kitty][Kitty Graphics Protocol], [iTerm2], or [wezterm]\nterminal, or a terminal that supports the sixel protocol, images can be shown\nin full resolution.\n\n-p kitty,  -p iterm2, or -p sixel | -p quarter | -p half |\n----------------------------------|------------|---------|\n ![](img/pixelation-kitty.png) | ![](img/pixelation-quarter.png) | ![](img/pixelation-half.png) |\n\n#### Grid display\n\nImages can be shown in a grid, which is very useful if you quickly want to\nbrowse through a lot of images. You can choose to show the filename as title,\nso it is easy to find exactly the filename you're looking for (The following\ngrid uses `--grid=2` and is pixelated `-p iterm2`).\n\n![Grid view of 4 pictures](img/grid-timg-wezterm.png)\n\u003cdetails\u003e\n\u003csummary\u003eThis is how the same grid looks if no high-res mode is available with - `-p quarter` ...\u003c/summary\u003e\n\n![](./img/grid-timg.png)\n\n\u003c/details\u003e\n\n### Synopsis\n\n```\nusage: timg [options] \u003cimage/video\u003e [\u003cimage/video\u003e...]\nOptions (most common first):\n        -p\u003cpixelation\u003e : Pixelation: 'h' = half blocks    'q' = quarter blocks\n                                     'k' = kitty graphics 'i' = iTerm2 graphics\n                                     's' = sixel graphics\n                         Default: Auto-detect graphics, otherwise 'quarter'.\n        --grid=\u003ccols\u003e[x\u003crows\u003e] : Arrange images in a grid (\"contact sheet\").\n        -C, --center   : Center image horizontally in available cell.\n        --title[=\u003cfmt_str\u003e]: Print title above each image. Accepts the following\n                         format parameters: %f = full filename; %b = basename\n                                            %w = image width; %h = height\n                                            %D = internal decoder used\n                         If no parameter is given, defaults to \"%f\"\n                         Env-var override with TIMG_DEFAULT_TITLE\n        -f\u003cfilelist\u003e   : Read newline-separated list of image files to show.\n                         Relative filenames are relative to current directory.\n                         (-f and -F can be provided multiple times.)\n        -F\u003cfilelist\u003e   : like -f, but relative filenames considered relative\n                         to the directory containing the filelist.\n        -b\u003cstr\u003e        : Background color to use behind alpha channel. Format\n                         color name like 'yellow', '#rrggbb', 'auto' or 'none'.\n                        'auto' is terminal background color. (default 'auto').\n        -B\u003cstr\u003e        : Checkerboard pattern color to use on alpha.\n        --pattern-size=\u003cn\u003e : Integer factor scale of the checkerboard pattern.\n        --auto-crop[=\u003cpre-crop\u003e] : Crop away all same-color pixels around image.\n                         The optional pre-crop is the width of border to\n                         remove beforehand to get rid of an uneven border.\n        --rotate=\u003cexif|off\u003e : Rotate according to included exif orientation.\n                              or 'off'. Default: exif.\n        -W, --fit-width: Scale to fit width of available space, even if it\n                         exceeds height.\n        -U, --upscale[=i]: Allow Upscaling. If an image is smaller than the\n                         available frame (e.g. an icon), enlarge it to fit.\n                         Optional parameter 'i' only enlarges in integer steps.\n        --clear[=every]: Clear draw area first. Optional argument 'every' will\n                         clear before every image (useful with -w/-wr,\n                         but not with --grid)\n        -V             : Directly use Video subsystem. Don't probe image\n                         decoding first (useful, if you stream video from stdin)\n        -I             : Only  use Image subsystem. Don't attempt video decoding\n        -w\u003cseconds\u003e    : Wait time between images (default: 0.0).\n        -wr\u003cseconds\u003e   : like above, but wait time between rows in grid.\n        -a             : Switch off anti-aliasing (default: on).\n        -g\u003cw\u003ex\u003ch\u003e      : Output geometry in character cells. Partial geometry\n                         leaving out one value -g\u003cw\u003ex or -gx\u003ch\u003e is possible,\n                         the other value it then derived from the terminal size.\n                         Default derived from terminal size is 160x50\n        -o\u003coutfile\u003e    : Write to \u003coutfile\u003e instead of stdout.\n        -E             : Don't hide the cursor while showing images.\n        --compress[=level]: Only for -pk or -pi: Compress image data. More\n                         CPU use, but less used bandwidth. (default: 1)\n        --threads=\u003cn\u003e  : Run image decoding in parallel with n threads\n                         (Default 3, 3/4 #cores on this machine)\n        --color8       : Choose 8 bit color mode for -ph or -pq\n        --version      : Print detailed version including used libraries.\n                         (v1.5.3+)\n        --verbose      : Print some stats after images shown.\n        -h             : Print this help and exit.\n        --help         : Page through detailed manpage-like help and exit.\n\n  Scrolling\n        --scroll[=\u003cms\u003e]       : Scroll horizontally (optionally: delay ms (60)).\n        --delta-move=\u003cdx:dy\u003e  : delta x and delta y when scrolling (default:1:0)\n\n  For Animations, Scrolling, or Video\n  These options influence how long/often and what is shown.\n        --loops=\u003cnum\u003e : Number of runs through a full cycle. -1 means 'forever'.\n                        If not set, videos loop once, animated images forever\n                        unless there is more than one file to show.\n        --frames=\u003cnum\u003e: Only show first num frames (if looping, loop only these)\n        --frame-offset=\u003cnum\u003e: Start animation/video at this frame\n        -t\u003cseconds\u003e   : Stop after this time, independent of --loops or --frames\n```\n\n### Examples\n```bash\ntimg some-image.jpg                # display a static image\ntimg -g50x50 some-image.jpg        # display image fitting in box of 50x50 pixel\n\n# Multiple images\ntimg *.jpg                         # display all *.jpg images\ntimg --title *.jpg                 # .. show name in title (short option -F)\ntimg --title=\"%b (%wx%h)\" *.jpg    # show short filename and image size as title\ntimg --grid=3x2 *.jpg              # arrange in 3 columns, 2 rows in terminal\ntimg --fit-width --grid=3 *.jpg    # maximize use of column width (short: -W)\ntimg --grid=3 -t5 *.gif            # Load gifs one by one in grid. Play each for 5sec.\n\n# Putting it all together; making an alias to list images; let's call it ils = 'image ls'\n# This prints images two per row with a filename title. Only showing one frame\n# so for animated gifs only the first frame is shown statically.\n# With hi-res iTerm or Kitty terminals, consider more columns, e.g --grid=4x1\n# Put this line in your ~/.bashrc\nalias ils='timg --grid=2x1 --upscale=i --center --title --frames=1 '\n\n# ... using this alias on images outputs a useful column view\nils *.jpg *.gif\n\n# Read the list of images to load from a file. One filename per line.\nlocate \"*.jpg\" \u003e /tmp/allimg.txt ; timg -f /tmp/allimg.txt\n\n# Show a PDF document, use full width of terminal, trim away empty border\ntimg -W --auto-crop some-document.pdf\ntimg --frames=1 some-document.pdf    # Show a PDF, but only first page\n\n# Reading images from a pipe. The filename '-' means 'read from stdin.\n# In this example generating a QR code and have timg display it:\nqrencode -s1 -m2 \"http://timg.sh/\" -o- | timg -\n\n# Here, using gnuplot output right in the shell\necho \"set terminal png; plot sin(x);\" | gnuplot | timg -\n\n# Open an image from a URL. URLs are internally actually handled by the\n# video subsystem, so it is treated as a single-frame 'film', nevertheless,\n# many image-URLs just work. But some image-specific features, such as trimming\n# or scrolling, won't work.\ntimg --center https://i.kym-cdn.com/photos/images/newsfeed/000/406/282/2b8.jpg\n\n# Sometimes, it is necessary to manually crop a few pixels from an\n# uneven border before the auto-crop finds uniform color all-around to remove.\n# For example with --auto-crop=7 we'd remove first seven pixels around an image,\n# then do the regular auto-cropping.\n#\n# The following example loads an image from a URL; --auto-crop does not work with\n# that, so we have to get the content manually, e.g. with wget. Piping to\n# stdin works; in the following example the stdin input is designated with the\n# special filename '-'.\n#\n# For the following image, we need to remove 3 pixels all around before\n# auto-crop can take over removing the remaining whitespace successfully:\nwget -qO- https://imgs.xkcd.com/comics/a_better_idea.png | timg --auto-crop=3 -\n\ntimg multi-resolution.ico   # See all the bitmaps in multi-resolution icons-file\ntimg --frames=1 multi-resolution.ico  # See only the first bitmap in that file\n\ntimg some-video.mp4         # Watch a video.\n\n# Play content of webcam (This assumes video4linux2, but whatever input devices\n# are supported on your system with libavdevice-dev)\ntimg /dev/video0\n\n# If you read a video from a pipe, it is necessary to skip attempting the\n# image decode first as this will consume bytes from the pipe. Use -V option.\nyoutube-dl -q -o- -f'[height\u003c480]' 'https://youtu.be/dQw4w9WgXcQ' | timg -V -\n\n# Show animated gif, possibly limited by timeout, loops or frame-count\ntimg some-animated.gif      # show an animated gif forever (stop with Ctrl-C)\ntimg -t5 some-animated.gif                   # show animated gif for 5 seconds\ntimg --loops=3 some-animated.gif             # Loop animated gif 3 times\ntimg --frames=3 --loops=1 some-animated.gif  # Show only first three frames\ntimg --frames=1 some-animated.gif            # Show only first frame. Static image.\n\n# Scroll\ntimg --scroll some-image.jpg       # scroll a static image as banner (stop with Ctrl-C)\ntimg --scroll=100 some-image.jpg   # scroll with 100ms delay\n\n# Create a text with the ImageMagick 'convert' tool and send to timg to scroll\nconvert -size 1000x60 xc:none -fill red -gravity center -pointsize 42 \\\n        -draw 'text 0,0 \"Watchen the blinkenlights...\"' -trim png:-   \\\n      | timg --scroll=20 -\n\n# Scroll direction. Horizontally, vertically; how about diagonally ?\ntimg --scroll --delta-move=1:0 some-image.jpg  # scroll with dx=1 and dy=0, so horizontally.\ntimg --scroll --delta-move=-1:0 some-image.jpg # scroll horizontally in reverse direction.\ntimg --scroll --delta-move=0:2 some-image.jpg  # vertical, two pixels per step.\ntimg --scroll --delta-move=1:1 some-image.jpg  # diagonal, dx=1, dy=1\n\n# Background color for transparent images (SVG-compatible strings are supported)\n# and generally useful if you have a transparent PNG that is otherwise hard\n# to see on your terminal background.\ntimg -b auto some-transparent-image.png  # use terminal background if possible\ntimg -b none some-transparent-image.png  # Don't use blending\ntimg -b lightgreen some-transparent-image.png\ntimg -b 'rgb(0, 255, 0)' some-transparent-image.png\ntimg -b '#0000ff' some-transparent-image.png\n\n# Checkerboard/Photoshop-like background on transparent images\ntimg -b lightgray -B darkgray some-transparent-image.png\n\n# .. with adjustable size.\ntimg -b lightgray -B darkgray --pattern-size=4 some-transparent-image.png\n```\n\n##### Partially transparent icon on champagne-colored terminal emulator\n\n-b auto  | -b lightgreen | -b lightgreen -B yellow | -b none  |\n---------|---------------|-------------------------|----------|\n![](img/alpha-bauto.png) | ![](img/alpha-blightgreen.png)  | ![](img/alpha-blightgreen-Byellow.png) | ![](img/alpha-bnone.png)\n\n--pattern-size=1                       | --pattern-size=4 |\n---------------------------------------|--------------------------------------|\n![](img/alpha-blightgreen-Byellow.png) | ![](img/alpha-blightgreen-Byellow-4.png) |\n\n#### Include in file browsers\n\nThere are many terminal based file-browsers. Adding `timg` to their\nconfiguration is usually straight forward.\n```\n# Another use: can run use this in a fzf preview window:\necho some-image.jpg | fzf --preview='timg -E --frames=1 --loops=1 -g $(( $COLUMNS / 2 - 4 ))x$(( $FZF_PREVIEW_LINES * 2 )) {}'\n\n# Use in vifm. ~/.config/vifm/vifmrc\nfilextype *.avi,*.mp4,*.wmv,*.dat,*.3gp,*.ogv,*.mkv,*.mpg,*.mpeg,*.vob,\n         \\*.fl[icv],*.m2v,*.mov,*.webm,*.ts,*.mts,*.m4v,*.r[am],*.qt,*.divx,\n         \\*.as[fx]\n        \\ {View in timg}\n        \\ timg --title --center --clear %f,\n\nfilextype *.bmp,*.jpg,*.jpeg,*.png,*.gif,*.xpm\n        \\ {View in timg}\n        \\ timg --title --center --clear %f; read -n1 -s -r -p \"Press any key to return\",\n```\n\n#### Other fun things\n\n```bash\n# Also, you could store the output and cat later to your terminal...\ntimg -g80x40 some-image.jpg \u003e /tmp/imageout.txt\ncat /tmp/imageout.txt\n\n# Of course, you can redirect the output to somewhere else. I am not suggesting\n# that you rickroll some terminal by redirecting timg's output to a /dev/pts/*\n# you have access to, but you certainly could...\n\n# Of course, you can go really crazy by storing a cycle of an animation. Use xz\n# for compression as it seems to deal with this kind of stuff really well:\ntimg -g60x30 --loops=10 nyan.gif | xz \u003e /tmp/nyan.term.xz\n\n# ..now, replay the generated ANSI codes on the terminal. Since it would\n# rush through as fast as possible, we have to use a trick to wait between\n# frames: Each frame has a 'move cursor up' escape sequence that contains\n# an upper-case 'A'. We can latch on that to generate a delay between frames:\nxzcat /tmp/nyan.term.xz | gawk '/\\[.*A/ { system(\"sleep 0.1\"); } { print $0 }'\n\n# You can wrap all that in a loop to get an infinite repeat.\nwhile : ; do xzcat... ; done\n\n# (If you Ctrl-C that loop, you might need to use 'reset' for terminal sanity)\n```\n\n## Terminal considerations\n\nThis section contains some details that you only might need to ever look at if\nthe output is not as expected.\n\n### Many terminals support direct hi-res image output\n\nThe [Kitty], [iTerm2], and [wezterm] terminals as well as other\nmodern terminals such as [Konsole] or the terminal in [vscode] allow to\ndirectly display high-resolution pictures.\n\nIf `timg` is running in such a terminal, it will attempt to auto-detect that\nfeature and use that mode. If your terminal does support the feature but\ncan't be auto-detected, you can explicitly choose the pixelation option\nin question with command line flag or environment variable (see `timg --help`).\n(Please file an issue with `timg` if auto-detect does not work).\n\n#### VSCode Terminal\nThe terminal in [vscode] to display images in high-resolution, you\nneed to enable the _Terminal \u003e Integrated: Enable Images_ setting in vscode.\nOtherwise you have to explicitly choose `-pq` to show the 'block' images.\n\n#### In tmux\nThe terminal multiplexer `tmux` prevents high-resolution images as it filters\nout the escape codes.\nHowever, with some ... workarounds, `timg` can show such pictures\nin `tmux` \u003e= version 3.3 iff in a [kitty]-terminal.\n\nSo if you need hi-res pictures in tmux, use a kitty terminal; you\nalso have to explicitly set the pixelation to `-pk` (see `timg --help` for\ndetails).\n\n#### Sixel\nOther terminals support an older high-resolution [sixel]-protocol, which you\ncan choose with `-ps`. Note, for this to work in xterm, you need to invoke it\nwith `xterm -ti vt340`.\n\n#### High resolution and low bandwidth\nIf watching hi-res videos remotely is too slow (due to high bandwidth\nrequirements or simply because your terminal has to do more work), try\nsetting the environment variable `TIMG_ALLOW_FRAME_SKIP=1` to allow timg\nleaving out frames to stay on track (see `timg --help`, environment variable\nsection). You can also attempt to set the `--compress` level higher.\n\n### Half block and quarter block rendering\n\nTerminals that do not support high-resolution image output can still show\nimages by virtue of showing colored blocks.\n\nThe half block pixelation (`-p half`) uses the the unicode\ncharacter [▄](U+2584 - 'Lower Half Block')\n_or_ [▀](U+2580 - 'Upper Half Block') (depending on the\n[`TIMG_USE_UPPER_BLOCK`](#half-block-choice-of-rendering-block)\nenvironment variable). If the top and bottom color is the same, a simple\nspace with background color is used.\n\nThe quarter block pixelation (`-p quarter`) uses eight different blocks.\n\nWith both of these pixelations, choosing the foreground color and background\n24-bit color, `timg` can simulate 'pixels'. With the half-block pixelation,\nthis can assign the correct color to the two 'pixels' available in one\ncharacter cell, in the quarter pixelation, four 'pixels' have to share two\ncolors, so the color accuracy is slighlty worse but it allows for higher spatial\nresolution.\n\nThe `-p` command line flag allows to choose between `-p half`, `-p quarter`,\nalso possible to just shorten to `-ph` and `-pq`. Default is `-pq`\n(see [above](#pixelation) how this looks like).\n\nTerminals that don't support Unicode or 24 bit color will probably not show\na very pleasant output. For terminals that only do 8 bit color, use the\n`--color8` command line option.\n\n\n#### Half block: Choice of rendering block\n\nBy default, `timg` uses the 'lower half block' to show the pixels in `-p half`\nmode. Depending on the font the terminal is using, using the upper block might\nlook better, so it is possible to change the default with an environment\nvariable.\nPlay around with this value if the output looks poor on your terminal. I found\nthat on my system there is no difference for [`konsole`][konsole] or `xterm` but the\n[`cool-retro-term`][cool-retro-term] looks better with the lower block, this is why it is the default.\n\nIn some terminals, such as [alacritty] (and only with certain font sizes),\nthere seems to be the opposite working better. To change, set this environment\nvariable:\n\n```\nexport TIMG_USE_UPPER_BLOCK=1   # change default to use upper block.\n```\n(this only will work fully with `-p half`. In `-p quarter` mode, there are\nadditional blocks that can't be worked around)\n\n##### What a problematic choice of block looks like\n\nThe image generally looks a bit 'glitchy' if the terminal leaves little\nspace between blocks, so that the wrong background color shows on a single\nline between pixels.\nThis is likely not intended by the terminal emulator and possibly happening\non rounding issues of font height or similar.\n\nAnyway, we can work around it (fully in `-p half`, partially in `-p quarter`\nmode). In the following illustration you see how that looks like. If you\nsee that, change the `TIMG_USE_UPPER_BLOCK` environment variable.\n\n\nGlitchy. Change TIMG_USE_UPPER_BLOCK| Looks good\n------------------------------------|-------------------------------|\n![](img/needs-block-change.png)     | ![](img/block-ok.png)|\n\n#### Other artifacts\n\nSome terminals leave one pixel of horizontal space between characters that\nresult in fine vertical lines in the image.\nThat can't be worked around, send a bug or better pull request to your terminal\nemulator.\n\n#### Wrong font aspect ratio\n\nUsually, timg attempts to determine the font aspect ratio and apply some\ncorrection if it is off from the nominal 1:2. But if you notice that the\nimage displayed is not quite the right aspect ratio because of the terminals\nfont used, you can set an environment variable `TIMG_FONT_WIDTH_CORRECT` with\na factor to make it look correctly.\n\nIncreasing the visual width by 10% would be setting the value to 1.1 for\ninstance.\n\n```\nexport TIMG_FONT_WIDTH_CORRECT=1.1\ntimg myimage.jpg\n```\n\nThis is an environment variable, so that you can set it once to best fit your\nterminal emulator of choice and don't have to worry about later.\n\n##### Example\nTerminal font too narrow   | Correct. Here with `TIMG_FONT_WIDTH_CORRECT=1.375`\n---------------------------|-------------------------------|\n![](img/aspect-wrong.png)  | ![](img/aspect-right.png)|\n\n\n#### Sixel videos scroll or grid view looks like staircase\n\nIf you have a Sixel terminal in which you observe artifacts such as videos\n'scrolling' or the grid view not having images vertically aligned, you might\nneed to set the `TIMG_SIXEL_NEWLINE_WORKAROUND=1` environment variable.\n\nUnfortuantely, some Sixel terminals disagree if there is a newline after an\nimage or not.\n\n## Installation\n### Install pre-built package\n\n\u003ca href=\"https://repology.org/project/timg/versions\"\u003e\n\u003cimg src=\"https://repology.org/badge/vertical-allrepos/timg.svg\" alt=\"Packaging status\" align=\"right\"\u003e\n\u003c/a\u003e\n\n#### Debian-based systems\n\n```bash\nsudo apt install timg\n```\n\n#### NixOS or Nix package manager\n\n```bash\nnix-env -i timg\n```\n\n#### macOS\n\n```bash\nbrew install timg\n```\n\n#### Use AppImage\n\nThe [timg release page](https://github.com/hzeller/timg/releases/latest) also\nhas a _minimal_ binary in the [AppImage package format][AppImage].\nTo keep the size small, it does _not_ include video decoding or some more\nfancy image formats. It is good for many contexts or if you want to try out\n`timg`, but for a full-featured binary, use one from your distribution or\nbuild from source.\n\n### Build and Install from source\n\n#### Get dependencies on Debian/Ubuntu\n\n```bash\nsudo apt install cmake git g++ pkg-config\nsudo apt install libgraphicsmagick++-dev libturbojpeg-dev libexif-dev libswscale-dev libdeflate-dev librsvg2-dev libcairo-dev # needed libs\n\n# For sixel output.\nsudo apt install libsixel-dev\n\n# If you want to include video decoding, also install these additional libraries\nsudo apt install libavcodec-dev libavformat-dev\n\nsudo apt install libavdevice-dev # If you want to read from video devices such as v4l2\n\nsudo apt install libopenslide-dev # If you want to add OpenSlide images support\nsudo apt install libpoppler-glib-dev  # if WITH_POPPLER enabled.\n\nsudo apt install pandoc  # If you want to recreate the man page\n```\n\n#### Get dependencies on NixOS or Nix package manager\n\nThe dependencies are set-up in the shell.nix, so you're ready to go opening\na nix shell\n\n```bash\nnix-shell\n```\n\n#### Get dependencies on Fedora\n\n```bash\nsudo dnf install cmake git g++ pkg-config\nsudo dnf install GraphicsMagick-c++-devel turbojpeg-devel libexif-devel libswscale-free-devel librsvg2-devel cairo-devel libdeflate-devel poppler-glib-devel libsixel-devel qoi-devel\n\n# If you want to include video decoding, also install these additional libraries\nsudo dnf install libavcodec-free-devel libavformat-free-devel libavdevice-free-devel openslide-devel\n\nsudo dnf install pandoc  # If you want to recreate the man page\n```\n\n#### Get dependencies on macOS\n\n```bash\n# Homebrew needs to be available to install required dependencies\nbrew install cmake git GraphicsMagick webp jpeg-turbo libexif librsvg cairo  # needed libs\n\n# If you want to include video decoding, install these additional libraries\nbrew install ffmpeg\n\n# If you want to add OpenSlide images support\nbrew install openslide\n\nbrew install pandoc  # If you want to recreate the man page\n```\n\n#### Get repo and compile timg\n\nIn the script below you see that the build system allows for some\ncompile-time choices:\n\n  * **`WITH_LIBSIXEL`** Use libsixel to output images in [sixel] graphics\n     format. Default **ON**.\n  * **`WITH_VIDEO_DECODING`** allow for video decoding. Requires ffmpeg-related\n     libraries. You typically want this **ON** (default)\n     * **`WITH_VIDEO_DEVICE`** this allows for accessing connected video\n     devices, e.g. you can watch your webcam input (requires\n     `WITH_VIDEO_DECODING`).\n  * **`WITH_GRAPHICSMAGICK`** This is the main image loading library so you\n    typically want this **ON** (default).\n  * **`WITH_TURBOJPEG`** If enabled, uses this for faster jpeg file loading.\n     You typically want this **ON** (default).\n  * **`WITH_POPPLER`** High-quality and faster PDF renderer. Needs poppler\n    and cairo.\n    If not compiled-in, will fallback to GraphicsMagick, but that typically\n    results in lower quality renderings. Typically want this **ON** (default).\n  * **`WITH_RSVG`** High-quality SVG renderer. Needs librsvg and cairo.\n    If not compiled-in, will fallback to GraphicsMagick, but that typically\n    results in lower quality renderings. Typically want this **ON** (default).\n  * **`WITH_OPENSLIDE_SUPPORT`** Openslide is an image format used in scientific\n    applications. Rarely used, so default off, switch ON if needed.\n  * **`WITH_QOI_IMAGE`** Allow decoding of Quite Ok Image format [QOI]. Small\n     and simple, default **ON**.\n  * **`WITH_STB_IMAGE`** Compile the simpler STB image library directly into\n    the timg binary in cases where Graphicsmagick is not suitable for\n    dependency pruning reasons; output can be slower and of less quality.\n    It is default **ON** (default) but will always only attempted\n    after other image loading fails. Turn off if you can use GraphicsMagick and\n    want to reduce potential security vectors.\n\nYou can choose these options by providing `-D\u003coption\u003e=ON` on the cmake command\nline, see below.\n\n```bash\ngit clone https://github.com/hzeller/timg.git  # Get repo\ncd timg                     # Enter the checked out repository directory.\nmkdir build                 # Generate a dedicated build directory.\ncd build\n# cmake with your desired options, see descriptions above\ncmake ../ -DWITH_OPENSLIDE_SUPPORT=On\nmake\n\n# After compilation, you can run from build/src/timg or install on your system with\nsudo make install\n```\n\n[24-bit-term]: https://gist.github.com/XVilka/8346728\n[cool-retro-term]: https://github.com/Swordfish90/cool-retro-term\n[konsole]: https://konsole.kde.org/\n[alacritty]: https://github.com/alacritty/alacritty\n[Kitty]: https://sw.kovidgoyal.net/kitty/\n[Kitty Graphics Protocol]: https://sw.kovidgoyal.net/kitty/graphics-protocol.html\n[iTerm2]: https://iterm2.com/\n[iTerm2 Graphics Protocol]: https://iterm2.com/documentation-images.html\n[wezterm]: https://wezfurlong.org/wezterm/\n[sixel]: https://en.wikipedia.org/wiki/Sixel\n[QOI]: https://qoiformat.org/\n[vscode]: https://code.visualstudio.com/\n[AppImage]: https://appimage.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhzeller%2Ftimg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhzeller%2Ftimg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhzeller%2Ftimg/lists"}