Skip to content

docs: plain English README and AGENTS.md - #89

Merged
rubas merged 1 commit into
mainfrom
docs/plain-english
Sep 26, 2026
Merged

rubas merged 1 commit into
mainfrom
docs/plain-english

Conversation

@rubas

@rubas rubas commented Sep 26, 2026

Copy link
Copy Markdown
Owner

Before

Filesystem-path inputs trust the local filesystem. They allow file,crypto,data: the network is blocked, but file is required. It is the protocol that opens the path itself, and it also lets a local HLS/DASH playlist read its sibling segment files. protocol_whitelist applies uniformly to every open libavformat performs, so there is no way to keep the top-level file open while forbidding the nested ones, and a crafted on-disk manifest can therefore still point FFmpeg at other local files via a file: reference.

Problem

  • Long sentences and bold phrases made the README slow to read.
  • The README listed the unsafe operations in ffi_helpers.rs, but missed two of them.
  • AGENTS.md repeated the README on panics, the protocol whitelist, and the LGPL build.

After

  • The README goes from what the library is, to install, usage, requirements, errors, untrusted input, safety, and development. Plain English, short sentences.
  • AGENTS.md holds only the agent rules, the checks, and the steps to add an operation.
  • Words: README 1408 to 1071, AGENTS.md 691 to 481.
Fact fixes
  • The README list of unsafe operations missed codec_name and extradata in ffi_helpers.rs. The README now describes the module without a list that goes stale.
  • The README said a panic returns {:error, %{type: "nif_panic", ...}}. That is the raw NIF map; the public API returns {:error, %Exmpeg.Error{reason: :nif_panic}}.
  • task check also runs zizmor on the workflows; the README now says so and points to task --list instead of a copied task list.
  • Checked against the code: version 0.6.0, the three precompiled targets and NIF 2.17, rust-version = "1.98", FFmpeg 9.0.1 and the LGPL configure flags in release.yml, the error reasons in lib/exmpeg/error.ex, the 100 ms cancel check, both whitelists in input.rs, and the glibc floors (x86_64 2.35, aarch64 2.38) with objdump -T on the v0.6.0 release tarballs.

@rubas
rubas merged commit ef06aeb into main Sep 26, 2026
1 check passed
@rubas
rubas deleted the docs/plain-english branch September 26, 2026 21:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant