Testimonial: filtering to glance at ffprobe - how this repo saves me time

[alaestor]

I don't have a blog, but this is what I'd write if I did.

---

Disclaimer

I'm very new to nushell and quite new to nix: I'm sure there are better ways to do everything I do. Feedback is always welcome.

Motivation - A Backstory No One Cares About

I'm looking for the same info 99% of the time I use ffprobe. I've run ffprobe for years, visually parsing out the information I cared about until I discovered nushell and this repo. I tried various tools and frontends in the past but I'd always hit limitations and end up doing it by hand, eye, and occasionally grep. It doesn't seem like much but it always took me a while, and there were little "gotcha's" that added extra effort and time: like how ffprobe and ffmpeg index streams differently by default (making me count streams and sanity-check map parameters etc). Doing it this way has probably burned hours of my life by this point.

nu-ffmpeg is a game-changer. It gave me structured ffprobe output I could easily use nushell to filter my way to the data I care about, and format it however I wanted.

Subtitles and Nu-er Shell

1. Adding steams subtitle. nu-ffmpeg provides helpers to retrieve structured data for audio and video streams but seemed to lack one for subtitles which was a common use-case for me, so I added it master...alaestor:nu-ffmpeg:master (I'd make a PR for this but I'm too dumb and disinterested to write tests/docs)

2. A newer shell. I'm using nushell 0.108 (current version in nixpkgs/unstable at time of writing) which nu-ffmpeg doesn't support. It seems there have been some changes to nushell which makes the setup and usage slightly different. I don't know what those changes are and I couldn't quite figure out how to adapt the instructions, so I just kinda made it up.

   First I locally packaged (my tweaked fork of) nu-ffmpeg, which I added to an overlay in my flake.

   nu-ffmpeg.nix

   {
     stdenvNoCC,
     fetchFromGitHub,
     unstableGitUpdater,
     lib,
   }: stdenvNoCC.mkDerivation rec {
     pname = "nu-ffmpeg";
     version = "0-unstable-2025-11-22";
     src = fetchFromGitHub {
       owner = "alaestor";
       repo = pname;
       rev = "1e00328a447ffb8108956f3ab8e0d71b276f230f";
       hash = "sha256-oN0/7PNInyyrsmBzBg23hDXVI6nDFwCCxHQkhhG75dc=";
       sparseCheckout = [
         "*.nu"
         "ffprobe"
         "get_ffprobe_commands_table"
         "get_filter_support_table"
       ];
     };
     dontBuild = true;
     dontUnpack = true;
     installPhase = ''
       cp -r ${src} $out
     '';
     passthru.updateScript = unstableGitUpdater { };
   
     meta = with lib; {
       description = "(personal fork) Utility commands for working with ffmpeg in nushell.";
       homepage = "https://github.com/alaestor/nu-ffmpeg";
       license = licenses.mit;
       platforms = platforms.all;
       maintainers = with maintainers; [];
     };
   }

   Then I put use ${pkgs.nu-ffmpeg}/ffprobe in my home-manager's programs.nushell.extraConfig

   (I haven't tried to get the ffmpeg side of nu-ffmpeg to work, which is a bit sad given the project's name... But it was beyond my scope as I'm only interested in making the ffprobe side of my life easier.)

Big win. Instead of trying to remember the various ffprobe arguments and visually parse things (or trying to grep...), now I could just run ffprobe file.mkv | ffprobe streams audio and use nushell to find whatever it was I wanted to see. Why ffprobe streams audio and not just streams audio? I don't know... I think it had something to do with newer nushell versions. But it works.

Custom Commands - Getting What I Want at a Glance

Having structured data that I could query and navigate through is great, but it opened the door to further time-savings. Next, I wanted short commands to get at the info I need most often: so I added some custom commands to programs.nushell.extraConfig

commands

programs.nushell.extraConfig = ''
#...
### nu-ffmpeg; ffprobe helper

use ${pkgs.nu-ffmpeg}/ffprobe

def ffpa [path] {(
  ffprobe $path
  | ffprobe streams audio
  | select tags.language? codec_name? tags?.BPS? tags?.DURATION? tags?.NUMBER_OF_BYTES? disposition?.default?
  | rename lang codec bps duration bytes default
  | update default {$in | into bool}
)}

def ffpv [path] {(
  ffprobe $path
  | ffprobe streams video
  | select codec_name? pix_fmt? width height? sample_aspect_ratio? display_aspect_ratio? r_frame_rate? field_order? tags?.BPS?
  | rename -c { codec_name: codec, sample_aspect_ratio: PAR, display_aspect_ratio: DAR, r_frame_rate: rate, field_order: field, tags.BPS: BPS }
)}

def ffps [path] {(
  ffprobe $path
  | ffprobe streams subtitle
  | select tags.language? codec_name? disposition?.default? disposition?.forced? tags?.NUMBER_OF_BYTES? tags?.title?
  | rename lang codec default forced bytes title
  | update default {$in | into bool}
  | update forced {$in | into bool}
)}

def ffp [path] {{
  file: (ls $path | select size name)
  video: (ffpv $path)
  audio: (ffpa $path)
  subtitle: (ffps $path)
}}
'';

The result is as seen in the picture at the top.

Text output of "ffp file.mkv"

╭──────────┬────────────────────────────────────────────────────────────────────────────────────────────╮
│          │ ╭───┬────────┬──────────╮                                                                  │
│ file     │ │ # │  size  │   name   │                                                                  │
│          │ ├───┼────────┼──────────┤                                                                  │
│          │ │ 0 │ 1.5 GB │ file.mkv │                                                                  │
│          │ ╰───┴────────┴──────────╯                                                                  │
│          │ ╭───┬───────┬─────────┬───────┬────────┬─────┬──────┬────────────┬─────────────┬─────────╮ │
│ video    │ │ # │ codec │ pix_fmt │ width │ height │ PAR │ DAR  │    rate    │    field    │   BPS   │ │
│          │ ├───┼───────┼─────────┼───────┼────────┼─────┼──────┼────────────┼─────────────┼─────────┤ │
│          │ │ 0 │ h264  │ yuv420p │  1920 │   1080 │ 1:1 │ 16:9 │ 24000/1001 │ progressive │ 7980514 │ │
│          │ ╰───┴───────┴─────────┴───────┴────────┴─────┴──────┴────────────┴─────────────┴─────────╯ │
│          │ ╭───┬──────┬───────┬────────┬────────────────────┬──────────┬─────────╮                    │
│ audio    │ │ # │ lang │ codec │  bps   │      duration      │  bytes   │ default │                    │
│          │ ├───┼──────┼───────┼────────┼────────────────────┼──────────┼─────────┤                    │
│          │ │ 0 │ jpn  │ aac   │ 192000 │ 00:23:50.058000000 │ 34321409 │ true    │                    │
│          │ │ 1 │ eng  │ aac   │ 192000 │ 00:23:50.058000000 │ 34321409 │ false   │                    │
│          │ ╰───┴──────┴───────┴────────┴────────────────────┴──────────┴─────────╯                    │
│          │ ╭────┬──────┬────────┬─────────┬────────┬───────┬────────────────╮                         │
│ subtitle │ │  # │ lang │ codec  │ default │ forced │ bytes │     title      │                         │
│          │ ├────┼──────┼────────┼─────────┼────────┼───────┼────────────────┤                         │
│          │ │  0 │ eng  │ ass    │ false   │ true   │ 409   │ Forced         │                         │
│          │ │  1 │ eng  │ ass    │ true    │ false  │ 26696 │                │                         │
│          │ │  2 │ eng  │ subrip │ false   │ false  │ 14464 │ CC             │                         │
│          │ │  3 │ ara  │ ass    │ false   │ false  │ 32437 │ Saudi Arabia   │                         │
│          │ │  4 │ ger  │ ass    │ false   │ false  │ 26431 │                │                         │
│          │ │  5 │ ger  │ subrip │ false   │ false  │ 16447 │ CC             │                         │
│          │ │  6 │ spa  │ ass    │ false   │ false  │ 22355 │ Latin American │                         │
│          │ │  7 │ spa  │ ass    │ false   │ false  │ 22238 │ European       │                         │
│          │ │  8 │ fre  │ ass    │ false   │ false  │ 24314 │                │                         │
│          │ │  9 │ fre  │ subrip │ false   │ false  │ 18712 │ CC             │                         │
│          │ │ 10 │ ind  │ ass    │ false   │ false  │ 28639 │                │                         │
│          │ │ 11 │ ita  │ ass    │ false   │ false  │ 24855 │                │                         │
│          │ │ 12 │ may  │ ass    │ false   │ false  │ 26297 │                │                         │
│          │ │ 13 │ por  │ ass    │ false   │ false  │ 26298 │ Brazilian      │                         │
│          │ │ 14 │ rus  │ ass    │ false   │ false  │ 30275 │                │                         │
│          │ │ 15 │ tha  │ ass    │ false   │ false  │ 49173 │                │                         │
│          │ │ 16 │ vie  │ ass    │ false   │ false  │ 29162 │                │                         │
│          │ │ 17 │ chi  │ ass    │ false   │ false  │ 27127 │ China          │                         │
│          │ │ 18 │ chi  │ ass    │ false   │ false  │ 27127 │ Hong Kong      │                         │
│          │ ╰────┴──────┴────────┴─────────┴────────┴───────┴────────────────╯                         │
╰──────────┴────────────────────────────────────────────────────────────────────────────────────────────╯

The only hiccup to this (aside from not being composable) is that the video record is a bit larger than the typical terminal window, making nushell truncate the output to [table ...]s on smaller displays. This is mostly owing to the inclusion of field_order and PAR which aren't often used by most people who are dealing with modern formats.

But now, finally: three letters and a filepath gives me all the info I need from ffprobe on a daily basis, and in a very compact and structured format.

A big <3 to sbrow/nu-ffmpeg for making life easier

[sbrow]

Wow, never in a million years did I expect such a positive response! Thank you. While nushell is my favorite language, they do update it frequently, which breaks old stuff, and I never updated this repo because I didn't think anyone would use it 😆

My apologies for never including any ffmpeg examples in the repo, I should work on that. Basically any work with ffmpeg starts with ffmpeg cmd [<inputs>], which creates a record you can manipulate with filters. When you're done with manipulations, you pipe your command to | command to-args | ^ffmpeg ...$in

I'll try and update the library for the latest nushell version and then add some examples, but here's a few in case you're in a hurry:

use ffmpeg.nu;
use filters.nu *;

# Re-encode the video to 30fps
(
  ffmpeg cmd ['https://sample-videos.com/video321/mp4/720/big_buck_bunny_720p_1mb.mp4']
  | fps 30
  | ffmpeg run
)

use ffmpeg.nu;
use filters.nu *;

# Re-encode the video to 30fps, specifying inputs and outputs
# Equivalent to the previous example
(
  ffmpeg cmd ['https://sample-videos.com/video321/mp4/720/big_buck_bunny_720p_1mb.mp4']
  | filterchain ['0'] { fps 30 } ['video']
  | command to-args
  | ^ffmpeg ...$in 
)

[sbrow]

Everything on master should work with nushell 0.108.0 now. If you open a PR and link me a video that contains subtitles, I'd love to include your streams subtitle command in the repo 😃

[alaestor]

It's more you're code than mine; I just copy+pasted the streams audio function and replaced "audio" with "subtitle" xD The reason I didn't make a PR is because I was too lazy to write the docs and tests associated with it...

As for sample files, test5.mkv from the ietf-wg-cellar/matroska-test-files repo has several subrip subtitle streams.