telescope-media.nvim

demo.mp4

Preview IMAGES, PDF, EPUB, VIDEO, and FONTS from Neovim using Telescope. Keep in mind that this is a rewrite so some filetypes are not yet supported. Lastly, opening an image for the first time will lag as it is creating caches in /tmp/tele.media.cache directory.

SUPPORTS

Following are the filetypes that this picker supports.

Supported filetypes. I think.

• MOBI
• FB2
• EPUB
• PNG
• JPG
• JPEG
• JIFF
• SVG
• WEBP
• GIF
• OTF
• TTF
• WOFF
• WOFF2
• MP4
• MKV
• FLV
• 3GP
• WMV
• MOV
• WEBM
• MPG
• MPEG
• AVI
• OGG
• AA
• AAC
• AIFF
• ALAC
• MP3
• OPUS
• OGA
• MOGG
• WAV
• CDA
• WMA
• AI
• EPS
• PDF
• MARKDOWN
• TORRENT
• RFC822
• ODT
• DOCX

NOTE: This plugin is only supported in Linux.

PACKER

use({
  "dharmx/telescope-media.nvim",
  config = function()
    require("telescope").load_extension("media")
  end,
})

LAZY

{
  "dharmx/telescope-media.nvim",
  config = function()
    require("telescope").load_extension("media")
  end,
}

SETUP

require("telescope").load_extension("media")

CONFIG

This extension should be configured using the extensions field inside Telescope. However, you could also pass a table into the extension call.

-- explore and maybe contribute more
local canned = require("telescope._extensions.media.lib.canned")

require("telescope").setup({
  extensions = {
    media = {
      backend = "viu", -- image/gif backend
      flags = {
        viu = {
          move = true, -- GIF preview
        },
      },
      on_confirm_single = canned.single.copy_path,
      on_confirm_muliple = canned.multiple.bulk_copy,
      cache_path = vim.fn.stdpath("cache") .. "/media"),
    }
  }
})

-- NOTE: It should be noted that if media.attach_mappings key is added then
--       on_confirm_single/on_confirm_muliple will not be called as a consequence.
--       you will have to either call a canned function or, call your own
--       function manually inside attach_mappings.

DEFAULTS

{
  backend = "file",
  flags = {
    catimg = { move = false },
    chafa = { move = false },
    viu = { move = false },
    -- cannot calculate terminal paddings adjust them yourselves
    ueberzug = { xmove = -12, ymove = -3, warnings = true, supress_backend_warning = false },
  },
  callbacks = {
    on_confirm_single = function(...) require("telescope._extensions.media.lib.canned").single.copy_path(...) end,
    on_confirm_muliple = function(...) require("telescope._extensions.media.lib.canned").multiple.bulk_copy(...) end,
  },
  cache_path = "/tmp/media",
  preview_title = "Preview",
  results_title = "Files",
  prompt_title = "Media",
  cwd = vim.fn.getcwd(),
  preview = {
    check_mime_type = true,
    timeout = 200,
    redraw = false,
    wait = 10,
    fill = {
      mime = "",
      file = "~",
      error = ":",
      binary = "X",
      timeout = "+",
      permission = "╱",
    },
  },
  log = {
    plugin = "telescope-media",
    level = "warn",
    highlights = true,
    use_file = true,
    use_quickfix = false,
  },
}

ADD BACKEND

-- Registration.
local Rifle = require("telescope._extensions.media.rifle")
Rifle.image_backends({ "my_cool_backend", "--silent", "--loop=no" })
-- alternatively: Rifle.image_backends("my_cool_backend") -- no extra args
--                Rifle.image_backends({ "my_cool_backend" }) -- no extra args
--                Rifle.image_backends({ "my_cool_backend", "--still" }) -- [1] will be taken
--                Rifle.image_backends.my_cool_backend = { "my_cool_backend" } -- no extra args
Rifle.allows_gifs("my_cool_backend") -- backend supports GIFs

-- Optional. Global extension setup.
require("telescope").setup({
  extensions = {
    media = {
      backend = "my_cool_backend",
      flags = {
        pxv = {
          move = true,
          -- these will be parsed and concatenated into string[]
          extra_args = {
            size = "fit", -- after conversion: --size fit
            ["--frames"] = 5, -- after conversion: --frames 5
            -- make sure the returning value is either boolean/string/number
            columns = function(window, options)
              return window.w
            end,
            "-r", function(window, options) return window.h end,
            "-i",
          },
        },
      },
    },
  },
})
require("telescope").load_extension("media")

-- Use your backend by:
require("telescope").extensions.media.media({ -- On the fly setup.
  backend = "my_cool_backend",
  flags = {
    my_cool_backend = {
      move = false,
      extra_args = { "--still" }, -- previous values will be discarded.
    },
  },
})

-- For VimL folks:
-- :Telescope media backend=my_cool_backend

COMMANDS

:Telescope media

"Using lua function
lua require('telescope').extensions.media.media()
lua << EOF
require('telescope').extensions.media.media({
  find_command = {
    "rg",
    "--files",
    "--glob",
    "*.{*}",
    "."
  }
})
EOF

PREREQUISITES

Some of these are optional.

• ueberzug is required for viewing images.
• ueberzugpp is required for viewing images.
• catimg is required for viewing images.
• jp2a is required for viewing images
• chafa is required for viewing images
• viu is required for viewing images
• ripgrep is optional but we use it by default.
• fontforge is for viewing fonts.
• poppler-utils is for viewing PDFs.
• epub-thumbnailer is for viewing EPUB.
• calibre is for viewing EPUB, FF2 and MOBI.
• transmission-cli for TORRENTs.
• aria2c for TORRENTs.
• odt2txt for ODT, SXW, ODS and ODP.
• xlsx2csv for XLSX.
• w3m for HTM, HTML and XHTML.
• elinks for HTM, HTML and XHTML.
• lynx for HTM, HTML and XHTML.
• pandoc for MARKDOWN, HTM, HTML, XHTML, ODT, SXW, ODS and ODP.
• mediainfo for audio files.
• exiftool for video files.
• glow for MARKDOWN.
• jupyter for IPYNB.
• jq for JSON.
• catdoc for MS-WORD and RTF.
• python for JSON.

TODOS

This is getting out of hand.

• Add documentations, briefs and notes.
• Add default text preview.
• Render html files using elinks, pandoc, lynx and w3m.
• Render markdown files using glow and pandoc.
• Add viu backend.
• Add jp2a backend.
• Add chafa backend.
• Add support for ZIPs.
• Add support for binaries.
• Add default image preview.
• Add support for ebooks.
• Add support for Ai/EPS.
• Add support for vectors.
• Add support for images.
• Add support for fonts.
• Add support for video thumbnails.
• Add support for audio covers.
• Add support for PDF.
• Add support for MSWORD types.
• Add support for XLSX.
• Add support for XLS.
• Add support for DJVU.
• Add support for TORRENT.
• Add support for ODS.
• Add support for ODP.
• Add support for SXW.
• Add support for ODT.
• Add support for DFF.
• Add support for DSF.
• Add support for WV.
• Add support for WVC.
• Add support for RFC822.
• Add support for RTF.
• Add support for MARKDOWN.
• Add some canned functions for config.on_confirm.
• Improve caching.
• Use image magick instead of fontforge for previewing fonts.
• Add text/binary file handlers.
• Add cwd support.
• Add attach_mappings support.
• Add img2txt backend.
• Add gif2txt backend.
• Add ascii-image-converter backend.
• Add dialog boxes.
• Add ffprobe backend for videos/gifs.
• Add rifle.lua.
• Revise rifle.lua.
• Recalibrate preview size when window is moved.
• Check only once if all listed executables in rifle.lua exists.
• Map executables to filetypes.
• Refactor and revise.
• Pass options for custom timeout limit for _run() function.
• Document preview.lua and rifle.lua.
• Revise all documentations.
• Add checkheath module.
• Do not use get_os_command_output for possible long jobs.

CREDITS

• tembokk
• telescope
• buffer_previewer
• ueberzug-og
• ueberzug
• ueberzugpp
• lua-sha
• ranger