VidTree

VidTree is a tiny CLI that shows how much video runtime lives inside a directory tree.

Think tree, but with video durations and folder totals. No FFmpeg required.

$ vidtree ~/Videos
Videos/                               2h 13m 44s · 6 videos
├── Go Course/                        1h 31m 20s · 4 videos
│   ├── 01 Introduction.mp4               12m 08s
│   ├── 02 Variables.mp4                  18m 42s
│   └── Concurrency/                      1h 00m 30s · 2 videos
│       ├── goroutines.mp4                 27m 11s
│       └── channels.mp4                   33m 19s
└── Linux/                              42m 24s · 2 videos
    ├── shell.mp4                         19m 02s
    └── permissions.mp4                   23m 22s

VidTree reads container metadata directly with pure-Go parsers. It does not decode media, execute external programs, or require FFmpeg, ffprobe, CGO, Python, or Node.js.

Installation

With Go 1.23 or newer:

go install github.com/syedmsawaid/vidtree@latest

Release archives for Linux, macOS, and Windows are also available from the GitHub Releases page.

Usage

Scan the current directory:

vidtree

Scan another directory:

vidtree ~/Videos

Usage:
  vidtree [path] [options]

Arguments:
  path                  Directory to scan (default: current directory)

Options:
  -d, --depth N         Maximum directory depth
  --files               Show individual video files (default)
  --no-files            Hide individual video files
  --sort MODE           Sort by name, duration, or count
  --reverse             Reverse sort order
  --hidden              Include hidden files and directories
  --no-color            Disable terminal colors
  --plain               ASCII/plain output
  --summary             Print only the summary
  --version             Show version
  -h, --help            Show help

Depth limits only what is displayed. Directory totals always include every scanned descendant.

Examples:

vidtree ~/Videos --no-files
vidtree ~/Videos --sort duration --reverse
vidtree ~/Videos --depth 2
vidtree ~/Videos --summary
vidtree ~/Videos --plain

Supported Formats

• MP4 (.mp4)
• QuickTime (.mov)
• M4V (.m4v)
• Matroska (.mkv)
• WebM (.webm)

Extensions are matched case-insensitively. Unsupported files are ignored. Broken supported files are shown as errors, excluded from duration and video totals, and reported without stopping the scan.

Behavior

• Hidden files and directories are skipped unless --hidden is set.
• Directory and file symlinks are not followed.
• Directories with no supported videos below them are omitted.
• Metadata probes use a bounded worker pool.
• Color is disabled when output is redirected, when NO_COLOR is set, or when --no-color or --plain is used.
• Output width defaults to 100 columns and honors the COLUMNS environment variable.

Build

git clone https://github.com/syedmsawaid/vidtree.git
cd vidtree
go build
./vidtree ~/Videos

Inject a release version with linker flags:

go build -ldflags "-X main.version=0.1.0"

Run project checks:

gofmt -w .
go test ./...
go vet ./...
go build ./...

Known Limitations

• Duration must be present in the MP4 movie header or Matroska segment info.
• Unfinalized, live, or unusual fragmented media may not contain a usable duration.
• VidTree does not inspect codecs, tracks, frame counts, or file sizes.
• Terminal width detection uses COLUMNS with a 100-column fallback.

Dependencies

VidTree implements the small EBML subset needed for safe Matroska duration reads and uses these focused pure-Go dependencies:

• github.com/abema/go-mp4, MIT license
• golang.org/x/term, BSD-3-Clause license

Neither invokes external executables. Their full license terms and those of transitive binary dependencies are in THIRD_PARTY_LICENSES and included in release archives.

License

VidTree is available under the MIT License.