image-rs / y4m

YUV4MPEG2 (.y4m) Encoder/Decoder

y4m

YUV4MPEG2 (.y4m) Encoder/Decoder. Format specification.

Usage

Simple stream copying:

extern crate y4m;
use std::io;

let mut infh = io::stdin();
let mut outfh = io::stdout();
let mut dec = y4m::decode(&mut infh).unwrap();
let mut enc = y4m::encode(dec.get_width(), dec.get_height(), dec.get_framerate())
    .with_colorspace(dec.get_colorspace())
    .write_header(&mut outfh)
    .unwrap();
loop {
    match dec.read_frame() {
        Ok(frame) => if enc.write_frame(&frame).is_err() { break },
        _ => break,
    }
}

See API documentation for overview of all available methods. See also this example on how to resize input y4m into grayscale y4m of different resolution:

cargo build --release --example resize
ffmpeg -i in.mkv -f yuv4mpegpipe - | target/release/examples/resize - 640x360 - | mpv -

License

Library is licensed under MIT.

y4m's Issues

Have the encoder/decoder own the Writer/Reader

The current structures are quite unwieldy once you start having a little more complex use-cases.

c6c592838222d749d3ca3aa00c58bdc78dada465 was an API break on a patch version bump

The breakage is still present in 0.5.2.

Support 10-bit y4m.

FFmpeg has an extension to y4m that supports 10-bit and above. rav1e will need this at some point.

I'm not sure if it's best to just return a [u8] for this or try to add methods that return [u16].

Move to image-rs

https://github.com/image-rs

from_u16 is not correct on big endian platforms

y4m is always little endian, however no endian swapping is performed, so the crate could produce incorrect results when run on a big endian machine.

compile with rav1e

rav1e]# cargo report future-incompatibilities --id 2 --package [email protected]
The following warnings were discovered during the build. These warnings are an
indication that the packages contain code that will become an error in a
future release of Rust. These warnings typically cover changes to close
soundness problems, unintended or undocumented behavior, or critical problems
that cannot be fixed in a backwards-compatible fashion, and are not expected
to be in wide use.

Each warning should contain a link for more information on what the warning
means and how to resolve it.

To solve this problem, you can try the following approaches:

• If the issue is not solved by updating the dependencies, a fix has to be
  implemented by those dependencies. You can help with that by notifying the
  maintainers of this problem (e.g. by creating a bug report) or by proposing a
  fix to the maintainers (e.g. by creating a pull request):

  • [email protected]
  • Repository: https://github.com/image-rs/y4m.git
  • Detailed warning command: cargo report future-incompatibilities --id 2 --package [email protected]

• If waiting for an upstream fix is not an option, you can use the [patch]
  section in Cargo.toml to use your own version of the dependency. For more
  information, see:
  https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html#the-patch-section

The package y4m v0.7.0 currently triggers the following future incompatibility lints:

warning: trailing semicolon in macro used in expression position
--> /root/.cargo/registry/src/github.com-1ecc6299db9ec823/y4m-0.7.0/src/lib.rs:110:42
|
110 | return Err(Error::ParseError($p));
| ^
...
155 | parse_error!(ParseError::General)
| --------------------------------- in this macro invocation
|
= warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
= note: for more information, see issue #79813 rust-lang/rust#79813
= note: macro invocations at the end of a block are treated as expressions
= note: to ignore the value produced by the macro, add a semicolon after the invocation of parse_error
= note: #[allow(semicolon_in_expressions_from_macros)] on by default
= note: this warning originates in the macro parse_error (in Nightly builds, run with -Z macro-backtrace for more info)

warning: trailing semicolon in macro used in expression position
--> /root/.cargo/registry/src/github.com-1ecc6299db9ec823/y4m-0.7.0/src/lib.rs:110:42
|
110 | return Err(Error::ParseError($p));
| ^
...
183 | parse_error!(ParseError::General)
| --------------------------------- in this macro invocation
|
= warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
= note: for more information, see issue #79813 rust-lang/rust#79813
= note: macro invocations at the end of a block are treated as expressions
= note: to ignore the value produced by the macro, add a semicolon after the invocation of parse_error
= note: #[allow(semicolon_in_expressions_from_macros)] on by default
= note: this warning originates in the macro parse_error (in Nightly builds, run with -Z macro-backtrace for more info)

warning: trailing semicolon in macro used in expression position
--> /root/.cargo/registry/src/github.com-1ecc6299db9ec823/y4m-0.7.0/src/lib.rs:110:42
|
110 | return Err(Error::ParseError($p));
| ^
...
329 | parse_error!(ParseError::InvalidY4M)
| ------------------------------------ in this macro invocation
|
= warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
= note: for more information, see issue #79813 rust-lang/rust#79813
= note: macro invocations at the end of a block are treated as expressions
= note: to ignore the value produced by the macro, add a semicolon after the invocation of parse_error
= note: #[allow(semicolon_in_expressions_from_macros)] on by default
= note: this warning originates in the macro parse_error (in Nightly builds, run with -Z macro-backtrace for more info)

warning: trailing semicolon in macro used in expression position
--> /root/.cargo/registry/src/github.com-1ecc6299db9ec823/y4m-0.7.0/src/lib.rs:110:42
|
110 | return Err(Error::ParseError($p));
| ^
...
374 | parse_error!(ParseError::General)
| --------------------------------- in this macro invocation
|
= warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
= note: for more information, see issue #79813 rust-lang/rust#79813
= note: macro invocations at the end of a block are treated as expressions
= note: to ignore the value produced by the macro, add a semicolon after the invocation of parse_error
= note: #[allow(semicolon_in_expressions_from_macros)] on by default
= note: this warning originates in the macro parse_error (in Nightly builds, run with -Z macro-backtrace for more info)

warning: trailing semicolon in macro used in expression position
--> /root/.cargo/registry/src/github.com-1ecc6299db9ec823/y4m-0.7.0/src/lib.rs:110:42
|
110 | return Err(Error::ParseError($p));
| ^
...
401 | parse_error!(ParseError::InvalidY4M)
| ------------------------------------ in this macro invocation
|
= warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
= note: for more information, see issue #79813 rust-lang/rust#79813
= note: macro invocations at the end of a block are treated as expressions
= note: to ignore the value produced by the macro, add a semicolon after the invocation of parse_error
= note: #[allow(semicolon_in_expressions_from_macros)] on by default
= note: this warning originates in the macro parse_error (in Nightly builds, run with -Z macro-backtrace for more info)

warning: trailing semicolon in macro used in expression position
--> /root/.cargo/registry/src/github.com-1ecc6299db9ec823/y4m-0.7.0/src/lib.rs:110:42
|
110 | return Err(Error::ParseError($p));
| ^
...
408 | parse_error!(ParseError::InvalidY4M)
| ------------------------------------ in this macro invocation
|
= warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
= note: for more information, see issue #79813 rust-lang/rust#79813
= note: macro invocations at the end of a block are treated as expressions
= note: to ignore the value produced by the macro, add a semicolon after the invocation of parse_error
= note: #[allow(semicolon_in_expressions_from_macros)] on by default
= note: this warning originates in the macro parse_error (in Nightly builds, run with -Z macro-backtrace for more info)

cargo --version
cargo 1.68.0 (115f34552 2023-02-26)
rustup --version
rustup 1.25.2 (17db695f1 2023-02-01)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: The currently active rustc version is rustc 1.68.0 (2c8cc3432 2023-03-06)

centos 7.9 x64

Documentation dispute: C420 really same as C420mpeg2?

The description for Colorspace::C420mpeg2 now reads:

y4m/src/lib.rs

Line 248 in 58375d6

/// Found in some files. Same as `C420`.

However, sources that I can find disagree with this conclusion:

• https://chromium.googlesource.com/webm/libvpx/+/refs/heads/main/y4minput.c indicates that there is a half-pixel (relative to Y size) or quarter-pixel (relative to C size) displacement
• https://github.com/xiph/rav1e/blob/bc516fcd18bcc2de7f009c2837469c901f7c605f/src/bin/decoder/y4m.rs#L104 indicates that it's, well, different

I recommend changing the text to:

    /// 4:2:0 with alternated vertically-displaced chroma planes, 8-bit.
    C420paldv,
    /// 4:2:0 with consistently vertically-displaced chroma planes, 8-bit.
    C420mpeg2,

or something more specific than that, if people want to ask about "hey how alternated is that".

next release

Hi, it would be great to publish the next release (0.8.0, I guess) now that we have a couple new API features which I'd like to depend on. Thanks again for this great crate!

Allow Frame struct initialization with u16 data

When encoding at high bit depths, unless passing decoded frames right back to the encoder, we currently have to perform u16 to u8 conversions in order to initialize a Frame. The two options to do that that I am aware of are an unsafe from_raw_parts operation, or iterating over each input pixel to generate a new frame. It would be convenient to have a constructor for high bit depth data that could perform one of these options when fed u16 input. Alternatively, a frame could always maintain a u16 buffer and the encoder could write as u8 when outputting in 8-bit.

No protection against OoM on large width or height

As soon as a Decoder is constructed it reads in the width and the height and tries to allocate a buffer for the frame. This means that if the width or the height are too large and cause the allocation to fail, the application panics. I don't see a way to prevent this as a library user short of wrapping it in a catch_unwind(). Perhaps a maximum width and height setting could be added, so Decoder::new can return an error instead of OoM-panicking? Alternatively, maybe the buffer should be allocated when the first frame is read in so the user has the chance to check width and height?

Parametrize Frame and Encoder/Decoder with Colorspace

Encoder shouldn't allow to write frames with different pixel formats to the same stream.