search

meh / rust-ffmpeg

Safe FFmpeg wrapper.
Do What The F*ck You Want To Public License
454 stars 97 forks source link

Too many things are called Video #98

Open kornelski opened 6 years ago

kornelski commented 6 years ago

Although Rust's namespacing makes it absolutely possible to have different structs called Video, it is confusing in practice, especially in Rustdoc. Rustdoc does not show module name when displaying types in function signatures, so the API reference is unclear when something takes/returns frames or codecs. Same with structs called Input. Rustdoc's search also doesn't search module names, so it's not possible to search for video frame specifically.

ffmpeg::codec::decoder::video::Video ffmpeg::codec::encoder::video::Video ffmpeg::codec::video::Video ffmpeg::util::frame::video::Video

Another problem is that since ffmpeg-rs doesn't have its own documentation, it's necessary to read ffmpeg's C documentation instead. However, renamed/namespaced Rust names don't match ffmpeg's C names (e.g. AVFrame and AVCodec are both called Video here), which makes it extra difficult to cross-reference documentation with this crate.

I suggest using C names, just without the AV prefix.

meh commented 6 years ago

The issue is this is not a straightforward wrapper, if you want behavior compatible with FFmpeg you should be using the ffmpeg-sys, this is a higher level wrapper trying to be more rustic.

I agree that the lack of documentation is actually a problem tho, and the rustdoc output is suboptimal at best.

kornelski commented 6 years ago

I'd rather not work with ffmpeg-sys directly. I prefer the higher-level usability and safety that the wrapper is providing.

I'm hoping this crate is "like ffmpeg, but with C-isms turned into Rust-isms" rather than a new library that's trying to abstract ffmpeg away with a different architecture that just happens to use ffmpeg as a back-end.

That's because the audiovideo domain is full of quirks, so a thick abstraction layer is likely to be a leaky abstraction and I'm worried that a non-straightforward wrapper is just going to make debugging of what ffmpeg is doing harder.

If things are named and structured the same, then I can use the tons of C ffmpeg documentation and random internet answers to get help. If they're not, then I'm dependent on your documentation or learning both your API and ffmpeg's and figuring out the mapping between them.

kornelski commented 6 years ago

Related rustdoc bug: https://github.com/rust-lang/rfcs/pull/2114