{"id":13780567,"url":"https://github.com/occivink/mpv-image-viewer","last_synced_at":"2025-05-11T13:32:35.746Z","repository":{"id":48927929,"uuid":"115217800","full_name":"occivink/mpv-image-viewer","owner":"occivink","description":"Configuration, scripts and tips for using mpv as an image viewer","archived":false,"fork":false,"pushed_at":"2023-03-03T17:00:08.000Z","size":96,"stargazers_count":276,"open_issues_count":16,"forks_count":22,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-08-03T18:15:13.200Z","etag":null,"topics":["image-viewer","lua","mpv","script"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/occivink.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-12-23T19:40:52.000Z","updated_at":"2024-08-02T16:23:24.000Z","dependencies_parsed_at":"2024-01-15T22:44:25.630Z","dependency_job_id":"b76598a1-07e0-47ad-b47d-2c0fed374448","html_url":"https://github.com/occivink/mpv-image-viewer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/occivink%2Fmpv-image-viewer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/occivink%2Fmpv-image-viewer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/occivink%2Fmpv-image-viewer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/occivink%2Fmpv-image-viewer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/occivink","download_url":"https://codeload.github.com/occivink/mpv-image-viewer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225056841,"owners_count":17414221,"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":["image-viewer","lua","mpv","script"],"created_at":"2024-08-03T18:01:17.332Z","updated_at":"2024-11-17T15:31:21.247Z","avatar_url":"https://github.com/occivink.png","language":"Lua","funding_links":[],"categories":["Image Viewers","Image","Lua"],"sub_categories":[],"readme":"This repository aggregates configurations, scripts and tips for using [mpv](https://github.com/mpv-player/mpv) as an image viewer. The affectionate nickname `mvi` is given to mpv in such case.\n\nThis README assumes basic familiarity with mpv and its configuration. The information here should be platform-agnostic for the most part.\n\n[![demo](https://i.vimeocdn.com/filter/overlay?src0=https%3A%2F%2Fi.vimeocdn.com%2Fvideo%2F674986351_1280x720.jpg\u0026src1=https%3A%2F%2Ff.vimeocdn.com%2Fimages_v6%2Fshare%2Fplay_icon_overlay.png)](https://vimeo.com/249231479)\n\n# Why?\n\nmpv is a competent video player and sufficiently lightweight to use comfortably to view images. It features advanced scaling algorithms and color management, which are key features in an image viewer.  \nIt is also very extensible which allows us to compensate for some missing image viewer features easily.  \nIt won't compete with `feh` or the likes when it comes to size or startup time, but it is still plenty fast.\n\n# Configuration\n\nThere are several options for making an mvi configuration.  \n* Use the normal mpv config, and apply changes at runtime. You will need `detect-image.lua` and use [input sections](https://mpv.io/manual/master/#input-sections) and [profiles](https://mpv.io/manual/master/#profiles) to make this work.\n* Or create an entirely separate `~/.config/mvi/` directory and use the alias `alias mvi='mpv --config-dir=$HOME/.config/mvi'` \n\nThe first option is more complex, the second results in essentially two separate programs.\n\nThe examples `mpv.conf` and `input.conf` in this repository are commented to highlight (un)desirable settings.\n\n# Scripts\n\n## image-positioning.lua\n\nAdds several high-level commands to zoom and pan:\n\n`drag-to-pan`: pan the image with the cursor, while keeping the same part of the image under the cursor  \n`pan-follows-cursor`: pan the image in the direction of the cursor  \n`cursor-centric-zoom`: (de)zoom the video while keeping the same part of the image under the cursor  \n`align-border`: align the border of the image with the border of the window  \n`pan-image`: pan the image in a direction, optionally ignoring the zoom or forcing the image to stay visible  \n`rotate-video`: rotate the image in 90 degrees increment  \n`reset-pan-if-visible`: reset the pan if the entire image is visible  \n\nThere are no default bindings, see [`input.conf`](input.conf#L19-L67) for how to bind them.\n\n## status-line.lua\n\nAdds a status line that can show different properties in the corner of the window. By default it shows `filename [positon/total]` in the bottom left.\n\nCan be activated with the commands `status-line-enable`, `status-line-disable`, `status-line-toggle` and configured through [`status_line.conf`](script-opts/status_line.conf).\n\n## detect-image.lua\n\nAllows you to run specific commands when images are being displayed. Does not do anything by default, needs to be configured through [`detect_image.conf`](script-opts/detect_image.conf).\n\nFor example, this makes it possible to setup bindings that are only in effect with images, like so:\n```\ncommand_on_first_image_loaded=enable-section image-viewer\ncommand_on_non_image_loaded=disable-section image-viewer\n```\nWhere the 'image-viewer' bindings are specified like so [`input.conf`](input.conf#L96-L99).\n\n## minimap.lua\n\nAdds a minimap that displays the position of the image relative to the view.  \nCan be activated with `minimap-enable`, `minimap-disable`, `minimap-toggle` and configured through [`minimap.conf`](script-opts/minimap.conf).\n\n## ruler.lua\n\nAdds a `ruler` command that lets you measure positions, distances and angles in the image.\nCan be configured through [`ruler.conf`](script-opts/ruler.conf).\n\n## freeze-window.lua\n\nBy default, mpv automatically resizes the window when the current file changes to fit its size. This script freezes the window so that this does not happen. \nThere is no configuration.\n\n## Others\n\nSome other mpv scripts work well with mvi, here are a few (feel free to send a PR for others):\n\n[playlist-view](https://github.com/occivink/mpv-gallery-view): show all images in a grid view  \n[zones](https://github.com/wiiaboo/mpv-scripts/blob/master/zones.lua): send different commands depending on cursor position  \n[autoload](https://github.com/mpv-player/mpv/blob/master/TOOLS/lua/autoload.lua): automatically load all files in the same directory. Set `videos=no` and `audio=no` in `script-opts/autoload.conf` to only autoload images.  \n[delete-file](https://github.com/zenyd/mpv-scripts#delete-file): delete the current file  \n[mpv_crop_script](https://github.com/TheAMM/mpv_crop_script): featureful screenshot tool  \n[auto-profiles](https://github.com/wiiaboo/mpv-scripts/blob/master/auto-profiles.lua): apply profiles conditionally. Can be used to lower settings with huge images  \n[crop](https://github.com/occivink/mpv-scripts#croplua): simple cropping script  \n[playlist-manager](https://github.com/jonniek/mpv-playlistmanager): playlist management script  \n[blacklist-extensions](https://github.com/occivink/mpv-scripts#blacklist-extensionslua): remove files from the playlist based on their types\n\n# Credits\n\nThanks to haasn for coming up first with the [image-viewer config](https://gist.github.com/haasn/7919afd765e308fa91cbe19a64631d0f), all the mpv devs and the /mpv/ funposters.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foccivink%2Fmpv-image-viewer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foccivink%2Fmpv-image-viewer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foccivink%2Fmpv-image-viewer/lists"}