Skip to content

Update the README and the programmers guide #262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cpncf merged 1 commit into from
Aug 10, 2026
+290 −84
Merged

Update the README and the programmers guide #262

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 72 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,12 @@ The OpenAPV supports the following features:
- fully compliant with 422-10, 422-12, 444-10, 444-12, 4444-10, 4444-12, and 400-10 profile of [APV codec](#apv-codec)
- Low complexity by optimization for ARM NEON and x86(64bit) SEE/AVX CPU
- Tile-based multi-threading
- Tile-based partial decoding, which decodes only the tiles an application asks for
- Various metadata including HDR10/10+ and user-defined format
- RGB content coding with the 444 profiles through color description signalling
- Constant QP (CQP) and average bitrate (ABR) rate control algorithms
- [APV Family](/readme/apv_family.md) configurations for typical target bitrate setting of encoder
- [APV Profile Extensions](/readme/profile_ext.md) defined by the OpenAPV project on top of the RFC 9924 profiles
- [APV Extensions](/readme/apv_ext.md) defined by the OpenAPV project on top of the RFC 9924 profiles: the 444-16C12 and 4444-16C12 profiles for 16-bit source companded to 12-bit, and the UNCONST profiles without the tile partitioning constraints


## APV codec
Expand All @@ -34,10 +35,11 @@ The APV codec standard has the following features:
- Various metadata including HDR10/10+ and user-defined format

### Related specification
- APV Codec (bitstream): [https://datatracker.ietf.org/doc/draft-lim-apv/](https://datatracker.ietf.org/doc/draft-lim-apv/)
- Scope of OpenAPV project
- APV Codec (bitstream): [RFC 9924](https://www.rfc-editor.org/rfc/rfc9924.html)
- APV ISO based media file format: [APV-ISOBMFF](/readme/apv_isobmff.md)
- APV RTP payload format: [https://datatracker.ietf.org/doc/draft-lim-rtp-apv/](https://datatracker.ietf.org/doc/draft-lim-rtp-apv/)
- APV RTP payload format: [https://datatracker.ietf.org/doc/draft-ietf-avtcore-rtp-apv/](https://datatracker.ietf.org/doc/draft-ietf-avtcore-rtp-apv/)
- APV Family: [APV-Family](/readme/apv_family.md)
- APV Extensions: [APV-Extensions](/readme/apv_ext.md)

## How to build
- Build Requirements
Expand Down Expand Up @@ -101,15 +103,47 @@ Displaying help:

oapv_app_enc --help

Encoding:
Encoding a raw YCbCr file, where the format has to be given, and a Y4M file,
which carries the format in its header:

oapv_app_enc -i input_1920x1080_yuv422_10bit.yuv -w 1920 -h 1080 -d 10 -z 30 --input-csp 2 -o encoded.apv
oapv_app_enc -i input.y4m -o encoded.apv

Choosing the quality. A fixed quantization parameter gives constant quality,
while a target bitrate lets the rate control pick the quantization parameter.
The preset trades encoding speed for compression efficiency:

oapv_app_enc -i input.y4m -q 25 --preset slow -o encoded.apv
oapv_app_enc -i input.y4m --bitrate 200mbps -o encoded.apv
oapv_app_enc -i input.y4m --family 422-HQ -o encoded.apv

Selecting a profile. The input is converted to the color space and bit depth
of the profile if needed:

oapv_app_enc -i input_12bit.y4m --profile 422-12 -q 25 -o encoded.apv
oapv_app_enc -i input_444_12bit.y4m --profile 444-12 -q 25 -o encoded.apv

Encoding RGB content (G/B/R planar order, coded as 444 with the identity matrix signalled in the color description; see the [Programmer's Guide](/readme/programmers_guide.md) for details):

oapv_app_enc -i input_rgb_gbr_planar_10bit.yuv -w 1920 -h 1080 -d 10 -z 30 --input-csp 3 --profile 444-10 --color-primaries 1 --color-transfer 13 --color-matrix 0 --color-range 1 -o encoded.apv

Controlling tiles and threads. Smaller tiles give more parallelism and
finer-grained partial decoding; the [APV Extensions](/readme/apv_ext.md)
profiles lift the tile size and count limits of RFC 9924:

oapv_app_enc -i input.y4m -q 25 --tile-w 256 --tile-h 256 -m 8 -o encoded.apv
oapv_app_enc -i input.y4m -q 25 --profile 422-10-UNCONST --tile-w 64 --tile-h 64 -o encoded.apv

Writing the reconstructed video and embedding a frame hash, so a decoder can
verify that it reconstructs exactly the same picture:

oapv_app_enc -i input.y4m -q 25 --hash -r recon.y4m -o encoded.apv

Encoding a part of the input, skipping the first 100 frames and coding the
next 50:

oapv_app_enc -i input.y4m -q 25 --seek 100 --max-au 50 -o encoded.apv

### Decoder

Decoder output can be in yuv or y4m formats.
Expand All @@ -118,16 +152,39 @@ Displaying help:

oapv_app_dec --help

Decoding:
Decoding to a Y4M file, which records the format, or to a raw YCbCr file:

oapv_app_dec -i encoded.apv -o output.y4m
oapv_app_dec -i encoded.apv -o output.yuv

Verifying the bitstream against the frame hash embedded by the encoder, and
decoding without writing any output, which is useful for timing:

oapv_app_dec -i encoded.apv --hash -v 3 -o output.y4m
oapv_app_dec -i encoded.apv -v 3

Converting the output. The bit depth can be changed and 422 content can be
written as P210:

oapv_app_dec -i encoded.apv -d 10 -o output.y4m
oapv_app_dec -i encoded.apv --output-csp 1 -o output.yuv

Decoding a limited number of access units with a fixed number of threads:

oapv_app_dec -i encoded.apv --max-au 50 -m 8 -o output.y4m

Decoding PBU by PBU with API set 1, which also allows decoding only a subset
of the tiles of each frame (see the [Programmer's Guide](/readme/programmers_guide.md)):

oapv_app_dec -i encoded.apv --api-set 1 -o output.y4m
oapv_app_dec -i encoded.apv --api-set 1 --cyclic-tile-decoding 4 -o output.y4m

## Programmer's guide

See the [Programmer's Guide](/readme/programmers_guide.md) for how to write
encoding and decoding code with the library, including PBU-based decoding,
tile-based partial decoding, runtime configuration, RGB content encoding,
and the custom memory allocator interface.
See the [Programmer's Guide](/readme/programmers_guide.md) for how to encode
and decode with the library, including PBU-based decoding, tile-based
partial decoding, runtime configuration, RGB content encoding, and the
custom memory allocator interface.

## Utility

Expand Down Expand Up @@ -207,6 +264,11 @@ cycle considerably.
See [LICENSE](LICENSE) file for details.

## Graphic logo

The black and the white logo below are meant for the opposite background, so
one of them blends into the page you are reading this on and looks blank.
Drag over it, or open the image file directly, to see it.

### logo
![OAPV](/readme/img/oapv_logo_bar_64.png) ![OAPV](/readme/img/oapv_logo_bar_128.png) ![OAPV](/readme/img/oapv_logo_bar_256.png) ![OAPV](/readme/img/oapv_logo_bar_512.png)

Expand Down
2 changes: 1 addition & 1 deletion readme/profile_ext.md → readme/apv_ext.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# APV Profile Extensions
# APV Extensions

This document defines additional APV profiles which are specified by the
OpenAPV project on top of [RFC 9924](https://www.rfc-editor.org/rfc/rfc9924.html).
Expand Down
Loading