Integrate merged AVIF decoder safeguards into source-depth API

This commit is contained in:
Dylan M. Taylor
2026-11-15 17:31:11 -05:00
171 changed files with 20879 additions and 1671 deletions
+3
View File
@@ -14,3 +14,6 @@ crates/font-store/index/sources.json -text
# The build fixture verifies these license files are copied byte-for-byte.
crates/fonts-build/tests/fixture/craft-fonts/fonts/**/OFL.txt -text
# DXF drawing goldens assert exact writer bytes, including LF on every platform.
crates/dxf/tests/data/drawing_*.dxf -text
+1
View File
@@ -6,6 +6,7 @@ author, source and license. Library code and original assets are under the repos
| File | Author | Source | License |
|---|---|---|---|
| `licenses/jpeg-encoder-0.6.1/`, `crates/image-codecs/NOTICE` | jpeg-encoder contributors and the IJG, libjpeg-turbo and SIMD authors named in the retained notices | [jpeg-encoder 0.6.1](https://crates.io/crates/jpeg-encoder/0.6.1), used unmodified; source checksums in `SOURCE.json` | (MIT OR Apache-2.0) AND IJG |
| `crates/smime/testdata/` | MailCraft contributors; RFC 9216 example certificates | [MailCraft at 240d1d42](https://github.com/UCS-Care-Group/mailcraft/tree/240d1d42fe394cf3274402b180663ba9b43ca180/crates/smime/testdata), restored unmodified; provenance in the directory README | MIT OR Apache-2.0 (source repository) |
| `licenses/dwg/acadrust-MPL-2.0.txt`, `licenses/dwg/acadrust-THIRD_PARTY_NOTICES.md` | `acadrust` contributors; ACadSharp authors for the noted ported routines | [acadrust 0.6.6](https://github.com/hakanaktt/acadrust), used unmodified as `craft-dwg`'s optional native dependency | MPL-2.0; embedded ACadSharp notice is MIT; see both retained files |
| `crates/cms/profiles/photocraft-coated-cmyk.icc` | PhotoCraft contributors; generated by `craft_cms::synth::coated_cmyk` | [PhotoCraft `crates/cms`](https://github.com/storytold/photocraft/tree/b3222ee8e7e6bcb4799c37f904c595f20f9baf5e/crates/cms) | CC0-1.0 |
Generated
+50 -41
View File
@@ -222,16 +222,6 @@ version = "1.0.104"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
[[package]]
name = "aotuv_lancer_vorbis_sys"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5bc4fd1a61860d2f1198b60bedd30910eaffa978f1ee6214dfb24ac70d589225"
dependencies = [
"cc",
"ogg_next_sys",
]
[[package]]
name = "arbitrary"
version = "1.5.0"
@@ -1414,7 +1404,6 @@ dependencies = [
"serde_json",
"symphonia",
"thiserror 2.0.21",
"vorbis_rs",
]
[[package]]
@@ -1425,6 +1414,7 @@ version = "0.1.0"
name = "craft-captions"
version = "0.1.0"
dependencies = [
"craft-media-testkit",
"craft-timeline",
"craft-xml",
"proptest",
@@ -1843,6 +1833,13 @@ dependencies = [
"image",
]
[[package]]
name = "craft-gzip"
version = "0.1.0"
dependencies = [
"flate2",
]
[[package]]
name = "craft-hdr"
version = "0.1.0"
@@ -1919,6 +1916,7 @@ dependencies = [
"avif-serialize",
"craft-heif",
"craft-jpeg",
"craft-media-testkit",
"craft-metadata",
"craft-video",
"crc32fast",
@@ -2075,6 +2073,14 @@ dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-mcp"
version = "0.1.0"
dependencies = [
"craft-jsonrpc",
"serde_json",
]
[[package]]
name = "craft-media"
version = "0.1.0"
@@ -2375,13 +2381,6 @@ dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-plist"
version = "0.1.0"
dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-platform"
version = "0.1.0"
@@ -2399,6 +2398,13 @@ dependencies = [
"zbus",
]
[[package]]
name = "craft-plist"
version = "0.1.0"
dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-plotter"
version = "0.1.0"
@@ -2696,6 +2702,7 @@ dependencies = [
"data-url",
"flate2",
"kurbo 0.13.1",
"quick-xml 0.41.0",
"resvg 0.48.1",
"roxmltree 0.21.2",
"thiserror 2.0.21",
@@ -2712,6 +2719,16 @@ dependencies = [
"kurbo 0.13.1",
]
[[package]]
name = "craft-tcraft"
version = "0.1.0"
dependencies = [
"craft-zip",
"serde",
"serde_json",
"thiserror 2.0.21",
]
[[package]]
name = "craft-text"
version = "0.1.0"
@@ -2827,6 +2844,14 @@ dependencies = [
"zip",
]
[[package]]
name = "craft-usd"
version = "0.1.0"
dependencies = [
"lz4_flex",
"thiserror 2.0.21",
]
[[package]]
name = "craft-vcard"
version = "0.1.0"
@@ -2841,6 +2866,7 @@ name = "craft-vectorcraft-format"
version = "0.1.0"
dependencies = [
"flate2",
"proptest",
"serde",
"serde_json",
"thiserror 2.0.21",
@@ -6025,6 +6051,12 @@ version = "0.1.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4050469837a6ff301cd14c1f8f24f88549e6d548f24f64e2148eb0f72cebc51f"
[[package]]
name = "lz4_flex"
version = "0.11.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "373f5eceeeab7925e0c1098212f2fbc4d416adec9d35051a6ab251e824c1854a"
[[package]]
name = "maybe-owned"
version = "0.3.4"
@@ -6783,15 +6815,6 @@ dependencies = [
"phf 0.11.3",
]
[[package]]
name = "ogg_next_sys"
version = "0.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed2d7a48e247c2bb07e633aefb65a38648ea58c7eedd4e4408a5861721ab049b"
dependencies = [
"cc",
]
[[package]]
name = "oid-registry"
version = "0.8.1"
@@ -10610,20 +10633,6 @@ version = "0.9.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
[[package]]
name = "vorbis_rs"
version = "0.5.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "49c5da94d280f7a27e8c937e9b73df2da3e23a2583f48471fd8fb4c72f9c1933"
dependencies = [
"aotuv_lancer_vorbis_sys",
"errno",
"getrandom 0.4.3",
"ogg_next_sys",
"thiserror 2.0.21",
"tinyvec",
]
[[package]]
name = "wait-timeout"
version = "0.2.1"
+4
View File
@@ -11,6 +11,7 @@ rust-version = "1.95"
repository = "https://github.com/storytold/craft-libs"
[workspace.dependencies]
craft-usd = { path = "crates/usd" }
craft-smime = { path = "crates/smime" }
craft-ber = { path = "crates/ber" }
craft-proto = { path = "crates/proto" }
@@ -38,6 +39,7 @@ hayro-syntax = { version = "=0.7.2", default-features = false, features = ["std"
bytemuck = "1"
kurbo = "0.13"
thiserror = "2"
craft-gzip = { path = "crates/gzip" }
craft-aaf = { path = "crates/aaf" }
craft-atomic = { path = "crates/atomic" }
craft-captions = { path = "crates/captions" }
@@ -91,6 +93,7 @@ craft-jmap = { path = "crates/jmap" }
craft-ical = { path = "crates/ical" }
craft-jpeg = { path = "crates/jpeg" }
craft-jsonrpc = { path = "crates/jsonrpc" }
craft-mcp = { path = "crates/mcp" }
craft-jxl = { path = "crates/jxl" }
craft-kiwi = { path = "crates/kiwi" }
craft-keymap = { path = "crates/keymap" }
@@ -145,6 +148,7 @@ craft-stencilcraft-document = { path = "crates/stencilcraft-document" }
craft-svg-paths = { path = "crates/svg-paths" }
craft-stream-codecs = { path = "crates/stream-codecs" }
craft-text = { path = "crates/text" }
craft-tcraft = { path = "crates/tcraft" }
craft-texture = { path = "crates/texture" }
craft-tga = { path = "crates/tga" }
craft-timeline = { path = "crates/timeline" }
+123
View File
@@ -296,3 +296,126 @@ implementation, https://github.com/macosforge/alac at c38887c5c5e64a4b31108733bd
(LICENSE-APACHE). The files are modified: translated to Rust, with bounds checks on hostile input,
wrapping integer arithmetic, the unrolled predictor and per-width matrix routines folded into one,
and the average bit rate filled in. Those files are Apache-2.0 only.
JPEG encoding dependency: jpeg-encoder 0.6.1
Source: https://crates.io/crates/jpeg-encoder/0.6.1
Declared license: (MIT OR Apache-2.0) AND IJG.
This software is based in part on the work of the Independent JPEG Group.
The MIT license and unaltered upstream IJG and SIMD notices follow. The Apache-2.0
alternative is also retained in licenses/jpeg-encoder-0.6.1 at the repository root.
The dependency is used unmodified; no encoder implementation is vendored here.
LICENSE-MIT
Copyright (c) 2021 Volker Ströbel <volkerstroebel@mysurdity.de>
Permission is hereby granted, free of charge, to any
person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the
Software without restriction, including without
limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software
is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice
shall be included in all copies or substantial portions
of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
Original src/fdct.rs opening notice
/*
* Ported from mozjpeg to rust
*
* This file was part of the Independent JPEG Group's software:
* Copyright (C) 1991-1996, Thomas G. Lane.
* libjpeg-turbo Modifications:
* Copyright (C) 2015, 2020, D. R. Commander.
*
* Conditions of distribution and use:
* In plain English:
*
* 1. We don't promise that this software works. (But if you find any bugs,
* please let us know!)
* 2. You can use this software for whatever you want. You don't have to pay us.
* 3. You may not pretend that you wrote this software. If you use it in a
* program, you must acknowledge somewhere in your documentation that
* you've used the IJG code.
*
* In legalese:
*
* The authors make NO WARRANTY or representation, either express or implied,
* with respect to this software, its quality, accuracy, merchantability, or
* fitness for a particular purpose. This software is provided "AS IS", and you,
* its user, assume the entire risk as to its quality and accuracy.
*
* This software is copyright (C) 1991-2020, Thomas G. Lane, Guido Vollbeding.
* All Rights Reserved except as specified below.
*
* Permission is hereby granted to use, copy, modify, and distribute this
* software (or portions thereof) for any purpose, without fee, subject to these
* conditions:
* (1) If any part of the source code for this software is distributed, then this
* README file must be included, with this copyright and no-warranty notice
* unaltered; and any additions, deletions, or changes to the original files
* must be clearly indicated in accompanying documentation.
* (2) If only executable code is distributed, then the accompanying
* documentation must state that "this software is based in part on the work of
* the Independent JPEG Group".
* (3) Permission for use of this software is granted only if the user accepts
* full responsibility for any undesirable consequences; the authors accept
* NO LIABILITY for damages of any kind.
*
* These conditions apply to any software derived from or based on the IJG code,
* not just to the unmodified library. If you use our work, you ought to
* acknowledge us.
*
* Permission is NOT granted for the use of any IJG author's name or company name
* in advertising or publicity relating to this software or products derived from
* it. This software may be referred to only as "the Independent JPEG Group's
* software".
*
* We specifically permit and encourage the use of this software as the basis of
* commercial products, provided that all warranty or liability claims are
* assumed by the product vendor.
*
* This file contains a slower but more accurate integer implementation of the
* forward DCT (Discrete Cosine Transform).
*
* A 2-D DCT can be done by 1-D DCT on each row followed by 1-D DCT
* on each column. Direct algorithms are also available, but they are
* much more complex and seem not to be any faster when reduced to code.
*
* This implementation is based on an algorithm described in
* C. Loeffler, A. Ligtenberg and G. Moschytz, "Practical Fast 1-D DCT
* Algorithms with 11 Multiplications", Proc. Int'l. Conf. on Acoustics,
* Speech, and Signal Processing 1989 (ICASSP '89), pp. 988-991.
* The primary algorithm described there uses 11 multiplies and 29 adds.
* We use their alternate method with 12 multiplies and 32 adds.
* The advantage of this method is that no data path contains more than one
* multiplication; this allows a very simple and accurate implementation in
* scaled fixed-point arithmetic, with a minimal number of shifts.
*/
Original src/avx2/fdct.rs opening notice
/*
* Ported from mozjpeg / jfdctint-avx2.asm to rust
* Copyright 2009 Pierre Ossman <ossman@cendio.se> for Cendio AB
* Copyright (C) 2009, 2016, 2018, 2020, D. R. Commander.
*
* Based on the x86 SIMD extension for IJG JPEG library
* Copyright (C) 1999-2006, MIYASAKA Masaru.
*/
+16
View File
@@ -108,3 +108,19 @@ fn objects_nested_too_deeply_are_an_error() {
let e = store::read(&chain(250)).unwrap_err();
assert!(e.contains("nested too deeply"), "{e}");
}
/// Many distinct property IDs still reject a duplicate without quadratic scanning.
#[test]
fn duplicate_after_many_distinct_properties_is_rejected() {
let mut props = vec![0x4C, 0x20];
props.extend_from_slice(&8193u16.to_le_bytes());
for id in (0..8192u16).chain(std::iter::once(7)) {
props.extend_from_slice(&id.to_le_bytes());
props.extend_from_slice(&0x82u16.to_le_bytes());
props.extend_from_slice(&0u16.to_le_bytes());
}
let mut writer = Writer::new(Version::V3);
writer.stream(Writer::ROOT, "properties", props).unwrap();
let e = store::read(&writer.finish()).unwrap_err();
assert!(e.contains("duplicate property id"), "{e}");
}
+3 -1
View File
@@ -461,11 +461,13 @@ impl R<'_> {
if at > props.len() {
return Err(bad("truncated property index"));
}
// A properties stream can name tens of thousands of ids: do not rescan all earlier ids.
let mut seen = std::collections::HashSet::with_capacity(n);
for i in 0..n {
let (Some(pid), Some(sf), Some(len)) = (rd_u16(&props, 4 + i * 6), rd_u16(&props, 6 + i * 6), rd_u16(&props, 8 + i * 6)) else {
return Err(bad("truncated property index"));
};
if o.props.iter().any(|(previous, _)| *previous == pid) {
if !seen.insert(pid) {
return Err(bad("duplicate property id"));
}
let v = props.get(at..at + len as usize).ok_or_else(|| bad("truncated property value"))?;
+1 -1
View File
@@ -21,7 +21,7 @@
//! transition's name) are not in the specification; they were first written by FilmCraft and keep
//! their names so that existing files read back.
pub(crate) mod bento;
pub mod bento;
mod read;
mod write;
+18 -7
View File
@@ -35,8 +35,8 @@
use std::collections::{BTreeMap, HashMap};
pub(crate) const MAGIC: [u8; 8] = [0xA4, b'C', b'M', 0xA5, b'H', b'd', b'r', 0xD7];
pub(crate) const LABEL_SIZE: usize = 24;
pub const MAGIC: [u8; 8] = [0xA4, b'C', b'M', 0xA5, b'H', b'd', b'r', 0xD7];
pub const LABEL_SIZE: usize = 24;
// standard object ids
const TOC_OBJECT: u32 = 1;
@@ -82,7 +82,7 @@ const MAX_VALUE_BYTES: usize = 16 << 20;
const MAX_NAME_BYTES: usize = 4 << 20;
/// Builds a Bento container.
pub(crate) struct Writer {
pub struct Writer {
data: Vec<u8>,
names: HashMap<(u32, String), u32>,
next: u32,
@@ -90,6 +90,12 @@ pub(crate) struct Writer {
entries: Vec<(u32, u32, u32, Vec<Seg>)>,
}
impl Default for Writer {
fn default() -> Self {
Self::new()
}
}
impl Writer {
pub fn new() -> Writer {
Writer { data: Vec::new(), names: HashMap::new(), next: MIN_USER_ID, entries: Vec::new() }
@@ -217,9 +223,9 @@ pub(crate) struct Prop {
}
/// A parsed Bento container.
pub(crate) struct Container<'a> {
pub struct Container<'a> {
data: &'a [u8],
pub objects: BTreeMap<u32, Vec<Prop>>,
pub(crate) objects: BTreeMap<u32, Vec<Prop>>,
names: HashMap<u32, String>,
by_name: HashMap<String, u32>,
}
@@ -229,11 +235,16 @@ fn be32(b: &[u8], at: usize) -> Option<u32> {
}
/// Whether `b` ends with a Bento label.
pub(crate) fn sniff(b: &[u8]) -> bool {
pub fn sniff(b: &[u8]) -> bool {
b.len() >= LABEL_SIZE && b[b.len() - LABEL_SIZE..b.len() - LABEL_SIZE + 8] == MAGIC
}
impl<'a> Container<'a> {
/// Object identifiers in ascending order.
pub fn object_ids(&self) -> impl Iterator<Item = u32> + '_ {
self.objects.keys().copied()
}
pub fn open(data: &'a [u8]) -> Result<Container<'a>, String> {
if !sniff(data) {
return Err("no Bento label at the end of the file".into());
@@ -324,7 +335,7 @@ impl<'a> Container<'a> {
}
/// The bytes of a value.
pub fn value(&self, p: &Prop) -> Result<Vec<u8>, String> {
pub(crate) fn value(&self, p: &Prop) -> Result<Vec<u8>, String> {
let total = p.segs.iter().try_fold(0usize, |total, s| {
let len = match s {
Seg::Imm(b) => b.len(),
+27
View File
@@ -0,0 +1,27 @@
use craft_aaf::omf::bento::{Container, Writer, sniff};
#[test]
fn external_consumer_reads_named_values_and_references() {
let mut writer = Writer::new();
let first = writer.new_object();
let second = writer.new_object();
writer.set(first, "test:value", "test:type", b"long value");
writer.set_references(first, &[second]);
let bytes = writer.finish();
assert!(sniff(&bytes));
let container = Container::open(&bytes).unwrap();
assert!(container.object_ids().any(|id| id == first));
assert_eq!(container.get(first, "test:value").as_deref(), Some(b"long value".as_slice()));
assert_eq!(container.resolve(first, second), second);
assert!(Container::open(&bytes[..bytes.len() - 1]).is_err());
}
#[test]
fn default_writer_builds_a_readable_empty_container() -> Result<(), String> {
let bytes = Writer::default().finish();
let container = Container::open(&bytes)?;
let ids: Vec<_> = container.object_ids().collect();
assert!(!ids.is_empty());
assert!(ids.windows(2).all(|pair| pair[0] < pair[1]));
Ok(())
}
+12 -6
View File
@@ -1,6 +1,6 @@
[package]
name = "craft-audio"
description = "Audio file I/O and codecs: WAV/AIFF read and write, FLAC encoder, AAC and ALAC decoders and encoders, AC-3/E-AC-3 decoder and encoder, MP3 decoder and encoder, Opus decoder and encoder, MP1/MP2 decoders."
description = "Audio file I/O and codecs: WAV/AIFF read and write, FLAC encoder, AAC and ALAC decoders and encoders, AC-3/E-AC-3 decoder and encoder, MP3 decoder and encoder, Opus decoder and encoder, Vorbis encoder, MP1/MP2 decoders."
version.workspace = true
edition.workspace = true
license.workspace = true
@@ -31,13 +31,18 @@ lossless-encode = ["pcm-encode", "flac-encode"]
pcm-encode = []
# Encode FLAC files.
flac-encode = ["craft-media/bitstream"]
# Encode Ogg Vorbis files (desktop only: builds the reference libvorbis from its C sources).
vorbis-encode = ["dep:vorbis_rs"]
# The pure-Rust Vorbis encoder (`vorbis::encoder`) and Ogg Vorbis files through `encode` and
# `encode_ogg_vorbis`.
vorbis-encode = ["craft-media/ogg"]
# Codec modules on their own, for packet-level use.
aac-decode = ["craft-media/bitstream"]
# The AAC encoder (`aac::Encoder`), and AAC in M4A through `encode` and `FileEncoder`.
aac-encode = ["craft-media/bitstream", "craft-media/isobmff"]
opus-decode = []
# QOA (Quite OK Audio) files: decoder and encoder in the `qoa` module, each on its own.
qoa = ["qoa-decode", "qoa-encode"]
qoa-decode = []
qoa-encode = []
opus-encode = []
ac3-decode = ["craft-media/bitstream"]
mpa-decode = ["craft-media/bitstream"]
@@ -68,9 +73,6 @@ rayon = { workspace = true, optional = true }
# symphonia keeps its AAC decoder for AAC in CAF, a container craft-media does not read.
symphonia = { version = "0.6.1", optional = true, default-features = false, features = ["mp3", "flac", "vorbis", "ogg", "wav", "pcm", "aiff", "isomp4", "aac", "alac", "adpcm", "caf", "mkv"] }
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
vorbis_rs = { version = "0.5", optional = true }
[dev-dependencies]
craft-media-testkit = { workspace = true }
proptest = { workspace = true }
@@ -84,6 +86,10 @@ required-features = ["decode", "lossless-encode", "peaks"]
name = "codecs"
required-features = ["decode", "encode"]
[[test]]
name = "qoa_oracle"
required-features = ["qoa"]
[[example]]
name = "info"
required-features = ["decode"]
+30 -3
View File
@@ -29,7 +29,7 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou
| `decode` | `decode`, `probe`, `Decoder`, `tracks`, `TrackDecoder`; every format in [Format support](#format-support) | `decode-native`, `symphonia` |
| `decode-native` | the same, native formats only (others are `Unsupported`); `wav_pcm`, `aiff_pcm` (a file's integer PCM bit for bit, as `RawPcm`) | the six decoders below, craft-media `isobmff`/`matroska`/`ogg`, `log` |
| `symphonia` | the fallback for formats with no native decoder; turning it on is the same as `decode` | `decode-native`, symphonia |
| `encode` | every encoder, and every format of `encode` and `FileEncoder` | `lossless-encode`, `aac-encode`, `alac-encode`, `ac3-encode`, `eac3-encode`, `mp3-encode`, `opus-encode` |
| `encode` | every encoder, and every format of `encode` and `FileEncoder` | `lossless-encode`, `aac-encode`, `alac-encode`, `ac3-encode`, `eac3-encode`, `mp3-encode`, `opus-encode`, `vorbis-encode` |
| `lossless-encode` | WAV, AIFF and FLAC writing | `pcm-encode`, `flac-encode` |
| `pcm-encode` | `encode`, `FileEncoder` for WAV and AIFF; `wav_float_header`; `pcm_wav_file`, `pcm_wav_header`, `pcm_aiff_file`, `pcm_aiff_header` (minimal files around integer PCM bytes, for essence embedded in AAF / OMF) | none |
| `flac-encode` | `encode`, `FileEncoder` for FLAC; `flac::Encoder`, the packet encoder for callers that mux FLAC themselves | craft-media `bitstream` |
@@ -37,6 +37,7 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou
| `alac-decode` | `alac::Decoder` | none |
| `alac-encode` | `alac::Encoder`; `encode`, `FileEncoder` for ALAC in M4A | craft-media `isobmff` |
| `opus-decode`, `opus-encode` | `opus::Decoder`/`StreamDecoder`, `opus::Encoder` | none |
| `vorbis-encode` | `vorbis::encoder::Encoder` (pure Rust); `encode_ogg_vorbis`, `encode_ogg` and `encode` for Ogg Vorbis files (whole buffer; not `FileEncoder`) | craft-media `ogg` |
| `ac3-decode` | `ac3::Decoder`, `ac3::ProgrammeDecoder` | craft-media `bitstream` |
| `ac3-encode`, `eac3-encode` | `ac3::encoder::Encoder`; `encode`, `FileEncoder` for AC-3 and E-AC-3 streams | craft-media `bitstream` |
| `mpa-decode` | `mpa::Decoder` | craft-media `bitstream` |
@@ -355,8 +356,12 @@ let pre_skip = enc.pre_skip(); // samples the player drops at the start
The encoder takes 48 kHz only, and craft-audio has no resampler.
craft-media has no Ogg muxer, so `.opus` files cannot be written yet; Opus goes into
Matroska/WebM or MP4:
Opus goes into Ogg, Matroska/WebM or MP4:
- **Ogg (`.opus`):** `craft_media::ogg::PageWriter` with `head` and `opus_tags` as the two header
packets, each packet's granule position the samples decoded so far (pre-skip included, as
the input above starts with it), and `finish(Some(pre_skip + length))` to trim the end
(RFC 7845 §4).
- **Matroska/WebM:** `head` is the track's `CodecPrivate`, and the pre-skip goes in
`TrackSpec::codec_delay_ns` (in nanoseconds at 48 kHz). The Matroska muxer cannot write
@@ -368,6 +373,27 @@ Matroska/WebM or MP4:
timescale), `segment_duration` the audio's length (movie timescale), `media_rate`
`0x0001_0000`.
### Encode Ogg Vorbis
```rust
use craft_audio::{OggVorbisOptions, encode_ogg_vorbis};
// 1–8 channels in Vorbis order (5.1: L C R Ls Rs LFE), any sample rate.
let opts = OggVorbisOptions::new(6.0).with_tag("TITLE", "Take 3").with_tag("ARTIST", "Me");
let ogg: Vec<u8> = encode_ogg_vorbis(&buf, &opts)?;
```
The encoder is pure Rust (`vorbis::encoder`, from FilmCraft #4481) and builds for wasm32. Quality
runs from -1 to 10 at a variable bit rate: about 18 kbit/s per channel at -1, 100 at 6 and 140
at 10 on music. `encode` with `EncodeFormat::Ogg` takes a WAV-order layout and writes it in
Vorbis order; its `RateControl::Bitrate` (64–500 kbit/s) picks the quality whose nominal rate
that is (`quality_for_bitrate`), and `RateControl::Quality` 0.0–1.0 is quality -1 to 10. For
streaming, feed `vorbis::encoder::Encoder` and write its packets with `craft_media::ogg::PageWriter`
(identification, `vorbis_comment`, setup, then the audio with each packet's granule position).
Not yet: short blocks (transients may pre-echo), channel coupling (stereo costs
about twice mono) and bit-rate management.
### Waveform overviews
```rust
@@ -704,6 +730,7 @@ the full tests with ffmpeg and the vectors required.
| MP3 encoder | FilmCraft `filmcraft-mp3enc` [4bec22b](https://github.com/storytold/filmcraft/commit/4bec22bd03bd1d995c9cf72e02a284f96d3d72cd) |
| ALAC | Apple's reference implementation [macosforge/alac@c38887c](https://github.com/macosforge/alac/tree/c38887c5c5e64a4b31108733bd79ca9b2496d987/codec), Copyright © 2011 Apple Inc., Apache-2.0; ported to Rust and modified (see the `alac` module docs and [NOTICE](../../NOTICE)) |
| Opus encoder | EffectCraft `effectcraft-opusenc` [c618429](https://github.com/storytold/effectcraft/commit/c618429252587525a2a6d4b5bccbe4ec5261e1b9) |
| Vorbis encoder | FilmCraft `filmcraft-vorbis` by @JordyUSA ([storytold/filmcraft#4481](https://github.com/storytold/filmcraft/pull/4481)), with partitions of whole sample frames so libvorbis reads surround |
Where apps had overlapping implementations, the one that measured better was kept, with the
tests of both:
+54
View File
@@ -343,6 +343,51 @@ impl AudioSpecificConfig {
}
}
/// Why an AudioSpecificConfig prefix cannot be written as an ADTS header.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AdtsConfigError {
/// Fewer than two bytes were supplied.
Short,
/// The prefix names a profile, indexed rate or channel configuration ADTS cannot carry.
Unsupported {
/// Audio object type from the prefix.
object_type: u8,
/// Sampling frequency index from the prefix.
sf_index: u8,
/// Channel configuration from the prefix.
channel_config: u8,
},
}
/// ADTS fixed fields taken from the prefix of an AudioSpecificConfig.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AdtsConfig {
/// Audio object type, 1 through 4.
pub object_type: u8,
/// Indexed sample rate, 0 through 12.
pub sf_index: u8,
/// Channel configuration, 1 through 7.
pub channel_config: u8,
}
impl AdtsConfig {
/// Parse only the first two ASC bytes. Unlike a decoder's full ASC parser, this accepts all
/// four object types representable by ADTS and rejects configurations needing a PCE.
pub fn from_asc_prefix(asc: &[u8]) -> std::result::Result<Self, AdtsConfigError> {
let (Some(&a), Some(&b)) = (asc.first(), asc.get(1)) else { return Err(AdtsConfigError::Short) };
let object_type = a >> 3;
let sf_index = ((a & 7) << 1) | (b >> 7);
let channel_config = (b >> 3) & 15;
if !(1..=4).contains(&object_type) || sf_index > 12 || !(1..=7).contains(&channel_config) {
return Err(AdtsConfigError::Unsupported { object_type, sf_index, channel_config });
}
Ok(Self { object_type, sf_index, channel_config })
}
/// Write a no-CRC ADTS header with variable-rate buffer fullness for one payload.
pub fn header(self, payload_len: usize) -> Result<[u8; 7]> {
AdtsHeader::write(self.object_type, self.sf_index, self.channel_config, payload_len, 0x7ff)
}
}
/// A parsed ADTS header.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -519,6 +564,15 @@ mod tests {
assert_eq!(AudioSpecificConfig::parse(&asc.to_bytes().unwrap()).unwrap(), asc);
}
#[test]
fn adts_config_preserves_prefix_and_frame_limits() {
let config = AdtsConfig::from_asc_prefix(&[0x12, 0x10]).unwrap();
assert_eq!(config.header(100).unwrap(), AdtsHeader::write(2, 4, 2, 100, 0x7ff).unwrap());
assert!(config.header(8185).is_err());
assert_eq!(AdtsConfig::from_asc_prefix(&[]), Err(AdtsConfigError::Short));
assert!(matches!(AdtsConfig::from_asc_prefix(&[0x2a, 0x10]), Err(AdtsConfigError::Unsupported { object_type: 5, .. })));
}
#[test]
fn adts_headers_refuse_fields_they_cannot_hold() {
for (object_type, sf_index, channel_config) in [(0, 4, 2), (5, 4, 2), (29, 4, 2), (2, 13, 2), (2, 15, 2), (2, 4, 8), (2, 4, 11), (2, 4, 12)] {
+1 -1
View File
@@ -60,7 +60,7 @@ mod tns;
#[cfg(feature = "aac-decode")]
pub(crate) use config::split_adts_upto;
pub use config::{AdtsHeader, AudioSpecificConfig, ElementType, ProgramConfig, config_layout, split_adts};
pub use config::{AdtsConfig, AdtsConfigError, AdtsHeader, AudioSpecificConfig, ElementType, ProgramConfig, config_layout, split_adts};
#[cfg(feature = "aac-decode")]
pub use decoder::Decoder;
#[cfg(feature = "aac-encode")]
+31 -13
View File
@@ -13,6 +13,8 @@
//! demuxers and [`TrackDecoder`]; everything else (FLAC, Vorbis, CAF, ADPCM, A-law, µ-law) through
//! `symphonia`, which is to be replaced by native decoders. Feature `decode-native` is the
//! same without symphonia.
//! - [`encode_ogg_vorbis`] and [`vorbis::encoder`] (feature `vorbis-encode`): Ogg Vorbis files
//! and Vorbis packets from a pure-Rust encoder, 1 to 8 channels, quality -1 to 10, with tags.
//! - [`TrackDecoder`] (any decoder feature): one track's packets from any demuxer to planar
//! `f32` in WAV channel order.
//! - [`encode`], [`FileEncoder`]: WAV/BWF/RF64 and AIFF/AIFF-C (feature `pcm-encode`, which also
@@ -27,7 +29,8 @@
//! - Codec modules for packet-level use, each with its own features: [`aac`] (`aac-decode`,
//! `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`, and
//! [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`]
//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-encode`: the packet encoder).
//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-encode`: the packet encoder), [`qoa`]
//! (`qoa-decode`, `qoa-encode`: whole QOA files).
//!
//! The shared types below build with no features.
@@ -49,12 +52,18 @@ pub mod opus;
mod pcm;
#[cfg(feature = "peaks")]
pub mod peaks;
#[cfg(any(feature = "qoa-decode", feature = "qoa-encode"))]
pub mod qoa;
#[cfg(feature = "decode-native")]
mod read;
#[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))]
mod track;
#[cfg(feature = "vorbis-encode")]
pub mod vorbis;
#[cfg(any(feature = "decode-native", feature = "pcm-encode"))]
mod wav;
/// Bounded WAV/RF64 cue, adtl and XMP marker metadata, without audio decoding.
pub mod wav_markers;
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
@@ -66,8 +75,11 @@ mod wav;
feature = "vorbis-encode"
))]
mod write;
/// Range-backed PCM WAVE access and a 16-bit PCM writer.
pub mod wav_range;
#[cfg(feature = "vorbis-encode")]
pub use write::{OGG_BITRATES, encode_ogg};
pub use write::{OGG_BITRATES, OggVorbisOptions, encode_ogg, encode_ogg_vorbis, quality_for_bitrate};
/// The FLAC packet encoder (RFC 9639), for a caller that muxes FLAC itself (into MP4, Matroska or
/// its own `.flac` writer): planar integer samples in, frames out, and the STREAMINFO to patch in
@@ -270,7 +282,9 @@ pub enum EncodeFormat {
Ac3,
/// An E-AC-3 stream: up to 7.1 at 32, 44.1 or 48 kHz.
Eac3,
/// Ogg Vorbis, whole-buffer encoding only.
/// Ogg Vorbis, 1–8 channels at any sample rate, whole-buffer encoding only. Variable bit
/// rate: a [`RateControl::Bitrate`] picks the quality whose nominal rate it is
/// ([`quality_for_bitrate`]), [`RateControl::Quality`] sets it directly.
Ogg,
}
@@ -371,7 +385,7 @@ impl EncodeFormat {
EncodeFormat::Mp3 => cfg!(feature = "mp3-encode"),
EncodeFormat::Ac3 => cfg!(feature = "ac3-encode"),
EncodeFormat::Eac3 => cfg!(feature = "eac3-encode"),
EncodeFormat::Ogg => cfg!(all(feature = "vorbis-encode", not(target_arch = "wasm32"))),
EncodeFormat::Ogg => cfg!(feature = "vorbis-encode"),
}
}
@@ -392,9 +406,9 @@ impl EncodeFormat {
pub fn max_channels(self) -> u16 {
match self {
EncodeFormat::Wav | EncodeFormat::Aiff => 32_767,
EncodeFormat::Flac | EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Eac3 => 8,
EncodeFormat::Flac | EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Eac3 | EncodeFormat::Ogg => 8,
EncodeFormat::Ac3 => 6,
EncodeFormat::Mp3 | EncodeFormat::Ogg => 2,
EncodeFormat::Mp3 => 2,
}
}
@@ -408,7 +422,10 @@ impl EncodeFormat {
EncodeFormat::Aac => &[&[0x4], &[0x3], &[0x7], &[0x107], &[0x607], &[0x60F], &[0x70F], &[0xFF]],
// Apple's layout tags for 1–8 channels, surrounds as back speakers.
EncodeFormat::Alac => &[&[0x4], &[0x3], &[0x7], &[0x107], &[0x37], &[0x3F], &[0x13F], &[0xFF]],
EncodeFormat::Mp3 | EncodeFormat::Ogg => &[&[0x4], &[0x3]],
EncodeFormat::Mp3 => &[&[0x4], &[0x3]],
// The Vorbis I §4.3.9 layouts for 1–8 channels (6.1 with a back centre and sides, 7.1
// with sides and backs), written in Vorbis order.
EncodeFormat::Ogg => &[&[0x4], &[0x3], &[0x7], &[0x33], &[0x37], &[0x3F], &[0x70F], &[0x63F]],
// The coding modes 1/0 to 3/2 with and without an LFE, by channel count.
EncodeFormat::Ac3 => &[&[0x4], &[0x3, 0xC], &[0x7, 0x103, 0xB], &[0x107, 0x603, 0xF, 0x10B], &[0x607, 0x10F, 0x60B], &[0x60F]],
// The same, and 7.1 with backs and sides.
@@ -450,10 +467,10 @@ impl EncodeFormat {
}
}
/// Whether the format takes [`RateControl::Quality`]: AAC. The other lossy formats are
/// written at a constant bit rate only.
/// Whether the format takes [`RateControl::Quality`]: AAC and Ogg Vorbis. The other lossy
/// formats are written at a constant bit rate only.
pub fn supports_quality(self) -> bool {
self == EncodeFormat::Aac
matches!(self, EncodeFormat::Aac | EncodeFormat::Ogg)
}
/// Whether the format loses audio: AAC, MP3, AC-3 and E-AC-3. These take
@@ -472,11 +489,12 @@ pub enum RateControl {
/// set of rates (MP3, AC-3) uses the highest one not above it; a rate outside what the
/// stream can carry is moved to the nearest one inside. AAC is written at 6 kbit/s or a
/// quarter of the sample rate per channel at least: from about half of that down its encoder
/// codes silence. Vorbis treats this as a VBR target (64–500 kbit/s), falling back to
/// a quality preset when that target is unsupported; it does not promise a constant bitrate.
/// codes silence. Vorbis takes 64–500 kbit/s and writes the quality whose nominal rate that is
/// ([`quality_for_bitrate`]); its rate varies with the audio.
Bitrate(u32),
/// A constant quality from 0.0 (smallest) to 1.0 (best), at whatever bit rate each frame
/// needs. AAC only; values outside the range are clamped, and NaN is an error.
/// needs. AAC and Vorbis (0.0 is Vorbis quality -1, 1.0 quality 10); values outside the range
/// are clamped, and NaN is an error.
Quality(f32),
}
+1 -135
View File
@@ -4,141 +4,7 @@
//! producing the N/2 "folded" time samples; the window overlap region is then unfolded against the
//! folded tail of the previous block, which the caller keeps in place in the output buffer.
#[derive(Clone, Copy, Default, Debug)]
pub struct Cpx {
pub re: f32,
pub im: f32,
}
impl Cpx {
#[inline]
fn mul(self, o: Cpx) -> Cpx {
Cpx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re }
}
#[inline]
fn add(self, o: Cpx) -> Cpx {
Cpx { re: self.re + o.re, im: self.im + o.im }
}
#[inline]
fn sub(self, o: Cpx) -> Cpx {
Cpx { re: self.re - o.re, im: self.im - o.im }
}
}
/// Mixed-radix (2, 3, 4, 5) forward complex FFT, unscaled. Radix 2, 3 and 4 use dedicated
/// butterflies; radix 5 uses a generic one.
pub struct Fft {
n: usize,
factors: Vec<usize>,
twiddle: Vec<Cpx>,
}
impl Fft {
pub fn new(n: usize) -> Fft {
let mut factors = Vec::new();
let mut m = n;
for p in [4usize, 2, 3, 5] {
while m.is_multiple_of(p) {
factors.push(p);
m /= p;
}
}
assert_eq!(m, 1, "unsupported FFT size {n}");
let twiddle = (0..n)
.map(|k| {
let ph = -2.0 * std::f64::consts::PI * k as f64 / n as f64;
Cpx { re: ph.cos() as f32, im: ph.sin() as f32 }
})
.collect();
Fft { n, factors, twiddle }
}
pub fn process(&self, data: &mut [Cpx], scratch: &mut Vec<Cpx>) {
scratch.clear();
scratch.extend_from_slice(&data[..self.n]);
self.rec(&mut data[..self.n], scratch, 1, self.n, 0, 1);
}
fn rec(&self, out: &mut [Cpx], inp: &[Cpx], in_stride: usize, n: usize, fi: usize, tw_stride: usize) {
let p = self.factors[fi];
let m = n / p;
if m == 1 {
for (i, o) in out.iter_mut().enumerate().take(p) {
*o = inp[i * in_stride];
}
} else {
for q in 0..p {
self.rec(&mut out[q * m..(q + 1) * m], &inp[q * in_stride..], in_stride * p, m, fi + 1, tw_stride * p);
}
}
let tw = &self.twiddle;
match p {
2 => {
for k in 0..m {
let a0 = out[k];
let a1 = out[m + k].mul(tw[k * tw_stride]);
out[k] = a0.add(a1);
out[m + k] = a0.sub(a1);
}
}
4 => {
for k in 0..m {
let t0 = out[k];
let t1 = out[m + k].mul(tw[k * tw_stride]);
let t2 = out[2 * m + k].mul(tw[2 * k * tw_stride]);
let t3 = out[3 * m + k].mul(tw[3 * k * tw_stride]);
let s0 = t0.add(t2);
let d0 = t0.sub(t2);
let s1 = t1.add(t3);
let d1 = t1.sub(t3);
out[k] = s0.add(s1);
out[2 * m + k] = s0.sub(s1);
// -j * d1 = (d1.im, -d1.re)
out[m + k] = Cpx { re: d0.re + d1.im, im: d0.im - d1.re };
out[3 * m + k] = Cpx { re: d0.re - d1.im, im: d0.im + d1.re };
}
}
3 => {
// sin(-2*pi/3) = -sqrt(3)/2
let h = tw[self.n / 3].im;
for k in 0..m {
let t0 = out[k];
let t1 = out[m + k].mul(tw[k * tw_stride]);
let t2 = out[2 * m + k].mul(tw[2 * k * tw_stride]);
let s = t1.add(t2);
let d = t1.sub(t2);
let a = Cpx { re: t0.re - 0.5 * s.re, im: t0.im - 0.5 * s.im };
out[k] = t0.add(s);
// j * h * d = (-h * d.im, h * d.re)
out[m + k] = Cpx { re: a.re - h * d.im, im: a.im + h * d.re };
out[2 * m + k] = Cpx { re: a.re + h * d.im, im: a.im - h * d.re };
}
}
_ => {
// Radix 5 (at most once per transform): generic butterfly with the five roots of
// unity looked up once.
let mut w5 = [Cpx::default(); 5];
for (q, w) in w5.iter_mut().enumerate() {
*w = tw[q * (self.n / p)];
}
let mut t = [Cpx::default(); 5];
for k in 0..m {
t[0] = out[k];
for q in 1..p {
t[q] = out[q * m + k].mul(tw[q * k * tw_stride]);
}
for q2 in 0..p {
let mut acc = t[0];
for q in 1..p {
acc = acc.add(t[q].mul(w5[(q * q2) % p]));
}
out[q2 * m + k] = acc;
}
}
}
}
}
}
use crate::opus::fft::{Cpx, Fft};
pub struct Imdct {
/// Full MDCT length (2x the number of coefficients).
+19 -327
View File
@@ -1,272 +1,45 @@
//! Pulse cache and bit allocation (RFC 6716 §4.3.3, §4.3.4.1).
use super::tables::{ALLOC, EBANDS, LOG2_FRAC_TABLE, MAX_LM, NB_EBANDS, OVERLAP};
use super::tables::{EBANDS, LOG2_FRAC_TABLE, MAX_LM, NB_EBANDS, OVERLAP};
use crate::opus::decode::range::{BITRES, RangeDecoder};
const MAX_PSEUDO: i32 = 40;
const LOG_MAX_PSEUDO: i32 = 6;
pub use crate::opus::rate_common::get_pulses;
#[cfg(test)]
use crate::opus::rate_common::log2_frac;
#[cfg(test)]
pub use crate::opus::rate_common::pvq_v;
pub const MAX_FINE_BITS: i32 = 8;
const FINE_OFFSET: i32 = 21;
pub const QTHETA_OFFSET: i32 = 4;
pub const QTHETA_OFFSET_TWOPHASE: i32 = 16;
const ALLOC_STEPS: i32 = 6;
/// Number of pulses represented by pseudo-pulse index `i`.
pub fn get_pulses(i: i32) -> i32 {
if i < 8 { i } else { (8 + (i & 7)) << ((i >> 3) - 1) }
}
/// Conservative (rounded up) log2 of `val` with `frac` fractional bits.
pub fn log2_frac(mut val: u32, mut frac: u32) -> i32 {
let mut l = crate::opus::decode::range::ilog(val);
if val & val.wrapping_sub(1) != 0 {
if l > 16 {
val = ((val - 1) >> (l - 16)) + 1;
} else {
val <<= 16 - l;
}
let mut l = (l - 1) << frac;
loop {
let b = (val >> 16) as i32;
l += b << frac;
val = (val + b as u32) >> b;
val = (val * val + 0x7FFF) >> 15;
if frac == 0 {
break;
}
frac -= 1;
}
l + (val > 0x8000) as i32
} else {
l -= 1;
l << frac
}
}
/// PVQ codebook size V(N, K) as u128 (saturating far above 2^32).
pub fn pvq_v(n: usize, k: usize) -> u128 {
// V(N,K) = V(N-1,K) + V(N,K-1) + V(N-1,K-1); computed row by row.
if k == 0 {
return 1;
}
if n == 0 {
return 0;
}
let mut row = vec![0u128; k + 1]; // V(0, k)
row[0] = 1;
for _ in 0..n {
let mut prev_diag = row[0]; // V(n-1, 0)
// V(n, 0) = 1
for kk in 1..=k {
let up = row[kk]; // V(n-1, kk)
let v = up.saturating_add(row[kk - 1]).saturating_add(prev_diag);
prev_diag = up;
row[kk] = v.min(u128::MAX >> 8);
}
row[0] = 1;
}
row[k]
}
fn fits_in32(n: usize, k: i32) -> bool {
pvq_v(n, k as usize) <= u32::MAX as u128
}
/// Precomputed per-mode data shared by all CELT decoders.
/// Decoder mode: shared allocation tables and decoder-specific inverse transforms.
pub struct Mode {
/// log2 of band width in 1/8 bits.
pub log_n: [i32; NB_EBANDS],
/// Index into `cache_bits` for `(LM+1)*NB_EBANDS + band` (-1 when unused).
pub cache_index: Vec<i16>,
/// `cache[0]` = max pseudo-pulses; `cache[k]` = bits(k) - 1 in 1/8 bits.
pub cache_bits: Vec<u8>,
/// Per-band maximum allocation: `[(2*LM + C-1)*NB_EBANDS + band]`.
pub caps: Vec<u8>,
core: crate::opus::rate_common::Mode,
pub window: [f32; OVERLAP],
pub mdct: [super::mdct::Imdct; MAX_LM + 1],
}
impl Mode {
pub fn new() -> Mode {
let mut log_n = [0i32; NB_EBANDS];
for (i, l) in log_n.iter_mut().enumerate() {
*l = log2_frac((EBANDS[i + 1] - EBANDS[i]) as u32, BITRES);
}
let (cache_index, cache_bits) = compute_pulse_cache(MAX_LM as i32);
let mut m = Mode {
log_n,
cache_index,
cache_bits,
caps: Vec::new(),
pub fn new() -> Self {
let mut mode = Self {
core: crate::opus::rate_common::Mode::new(),
window: [0.0; OVERLAP],
mdct: [super::mdct::Imdct::new(1920), super::mdct::Imdct::new(960), super::mdct::Imdct::new(480), super::mdct::Imdct::new(240)],
};
m.caps = compute_caps(&m);
for i in 0..OVERLAP {
let x = std::f64::consts::FRAC_PI_2 * (i as f64 + 0.5) / OVERLAP as f64;
let s = x.sin();
m.window[i] = (std::f64::consts::FRAC_PI_2 * s * s).sin() as f32;
mode.window[i] = (std::f64::consts::FRAC_PI_2 * s * s).sin() as f32;
}
m
}
#[inline]
pub fn cache(&self, lm: i32, band: usize) -> &[u8] {
let idx = self.cache_index[((lm + 1) as usize) * NB_EBANDS + band];
&self.cache_bits[idx.max(0) as usize..]
}
pub fn bits2pulses(&self, band: usize, lm: i32, bits: i32) -> i32 {
let cache = self.cache(lm, band);
let mut lo = 0i32;
let mut hi = cache[0] as i32;
let bits = bits - 1;
for _ in 0..LOG_MAX_PSEUDO {
let mid = (lo + hi + 1) >> 1;
if cache[mid as usize] as i32 >= bits {
hi = mid;
} else {
lo = mid;
}
}
let lo_bits = if lo == 0 { -1 } else { cache[lo as usize] as i32 };
if bits - lo_bits <= cache[hi as usize] as i32 - bits { lo } else { hi }
}
pub fn pulses2bits(&self, band: usize, lm: i32, pulses: i32) -> i32 {
if pulses == 0 { 0 } else { self.cache(lm, band)[pulses as usize] as i32 + 1 }
}
/// Per-band allocation caps for this frame (`init_caps`).
pub fn init_caps(&self, lm: usize, c: usize) -> [i32; NB_EBANDS] {
let mut cap = [0i32; NB_EBANDS];
for (i, cp) in cap.iter_mut().enumerate() {
let n = (EBANDS[i + 1] - EBANDS[i]) << lm;
*cp = ((self.caps[NB_EBANDS * (2 * lm + c - 1) + i] as i32 + 64) * c as i32 * n) >> 2;
}
cap
mode
}
}
fn compute_pulse_cache(lm_max: i32) -> (Vec<i16>, Vec<u8>) {
let nb = NB_EBANDS;
let rows = (lm_max + 2) as usize;
let mut index = vec![-1i16; nb * rows];
let mut entries: Vec<(usize, i32, usize)> = Vec::new(); // (N, K, offset)
let mut curr = 0usize;
for i in 0..rows {
for j in 0..nb {
let n = (((EBANDS[j + 1] - EBANDS[j]) << i) >> 1) as usize;
index[i * nb + j] = -1;
// Reuse the entry of an earlier band with the same size.
'search: for k in 0..=i {
for nn in 0..nb {
if k == i && nn >= j {
break;
}
if n == (((EBANDS[nn + 1] - EBANDS[nn]) << k) >> 1) as usize {
index[i * nb + j] = index[k * nb + nn];
break 'search;
}
}
}
if index[i * nb + j] == -1 && n != 0 {
let mut k = 0;
while k < MAX_PSEUDO && fits_in32(n, get_pulses(k + 1)) {
k += 1;
}
index[i * nb + j] = curr as i16;
entries.push((n, k, curr));
curr += (k + 1) as usize;
}
}
impl std::ops::Deref for Mode {
type Target = crate::opus::rate_common::Mode;
fn deref(&self) -> &Self::Target {
&self.core
}
let mut bits = vec![0u8; curr];
for &(n, k, off) in &entries {
let maxk = get_pulses(k) as usize;
let tmp = required_bits(n, maxk, BITRES);
for j in 1..=k {
bits[off + j as usize] = (tmp[get_pulses(j) as usize] - 1) as u8;
}
bits[off] = k as u8;
}
(index, bits)
}
/// Bits (1/2^frac units, rounded up) needed for each K in `0..=maxk` for dimension `n`.
fn required_bits(n: usize, maxk: usize, frac: u32) -> Vec<i32> {
let mut out = vec![0i32; maxk + 1];
if n == 1 {
for o in out.iter_mut().skip(1) {
*o = 1 << frac;
}
} else {
for (k, o) in out.iter_mut().enumerate().skip(1) {
let v = pvq_v(n, k);
*o = log2_frac(v as u32, frac);
}
}
out
}
fn compute_caps(m: &Mode) -> Vec<u8> {
let nb = NB_EBANDS;
let mut caps = vec![0u8; (MAX_LM + 1) * 2 * nb];
for i in 0..=MAX_LM as i32 {
for c in 1..=2i32 {
for j in 0..nb {
let mut n0 = EBANDS[j + 1] - EBANDS[j];
let max_bits = if n0 << i == 1 {
(c * (1 + MAX_FINE_BITS)) << BITRES
} else {
let mut lm0 = 0;
if n0 > 2 {
n0 >>= 1;
lm0 -= 1;
} else if n0 <= 1 {
lm0 = i.min(1);
n0 <<= lm0;
}
let pcache = m.cache(lm0, j);
let mut mb = pcache[pcache[0] as usize] as i32 + 1;
let mut n = n0;
for k in 0..(i - lm0) {
mb <<= 1;
let offset = ((m.log_n[j] + ((lm0 + k) << BITRES)) >> 1) - QTHETA_OFFSET;
let num = 459 * ((2 * n - 1) * offset + mb);
let den = ((2 * n - 1) << 9) - 459;
let qb = ((num + (den >> 1)) / den).min(57);
mb += qb;
n <<= 1;
}
if c == 2 {
mb <<= 1;
let offset = ((m.log_n[j] + (i << BITRES)) >> 1) - if n == 2 { QTHETA_OFFSET_TWOPHASE } else { QTHETA_OFFSET };
let ndof = 2 * n - 1 - (n == 2) as i32;
let p = if n == 2 { 512 } else { 487 };
let num = p * (mb + ndof * offset);
let den = (ndof << 9) - p;
let qb = ((num + (den >> 1)) / den).min(if n == 2 { 64 } else { 61 });
mb += qb;
}
let ndof = c * n + if c == 2 && n > 2 { 1 } else { 0 };
let mut offset = ((m.log_n[j] + (i << BITRES)) >> 1) - FINE_OFFSET;
if n == 2 {
offset += (1 << BITRES) >> 2;
}
let num = mb + ndof * offset;
let den = (ndof - 1) << BITRES;
let qb = ((num + (den >> 1)) / den).min(MAX_FINE_BITS);
mb += (c * qb) << BITRES;
mb
};
let w = c * ((EBANDS[j + 1] - EBANDS[j]) << i);
let v = (4 * max_bits / w) - 64;
caps[((i * 2 + c - 1) as usize) * nb + j] = v.clamp(0, 255) as u8;
}
}
}
caps
}
/// Result of the allocation process.
@@ -296,89 +69,8 @@ pub struct AllocationInput<'a, 'd> {
pub fn compute_allocation(input: AllocationInput<'_, '_>) -> Allocation {
let AllocationInput { mode: m, start, end, offsets, cap, trim: alloc_trim, total, channels: c, lm, decoder: dec } = input;
let ci = c as i32;
let lmi = lm as i32;
let mut total = total.max(0);
let mut skip_start = start;
let skip_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
total -= skip_rsv;
let mut intensity_rsv = 0;
let mut dual_stereo_rsv = 0;
if c == 2 {
intensity_rsv = LOG2_FRAC_TABLE[end - start];
if intensity_rsv > total {
intensity_rsv = 0;
} else {
total -= intensity_rsv;
dual_stereo_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
total -= dual_stereo_rsv;
}
}
let mut bits1 = [0i32; NB_EBANDS];
let mut bits2 = [0i32; NB_EBANDS];
let mut thresh = [0i32; NB_EBANDS];
let mut trim_offset = [0i32; NB_EBANDS];
for j in start..end {
let w = EBANDS[j + 1] - EBANDS[j];
thresh[j] = (ci << BITRES).max(((3 * w) << lmi << BITRES) >> 4);
trim_offset[j] = (ci * w * (alloc_trim - 5 - lmi) * (end as i32 - j as i32 - 1) * (1 << (lmi + BITRES as i32))) >> 6;
if w << lmi == 1 {
trim_offset[j] -= ci << BITRES;
}
}
let nb_alloc = ALLOC.len() as i32;
let mut lo = 1;
let mut hi = nb_alloc - 1;
loop {
let mut done = false;
let mut psum = 0;
let mid = (lo + hi) >> 1;
for j in (start..end).rev() {
let n = EBANDS[j + 1] - EBANDS[j];
let mut bitsj = (ci * n * (ALLOC[mid as usize][j] as i32)) << lmi >> 2;
if bitsj > 0 {
bitsj = (bitsj + trim_offset[j]).max(0);
}
bitsj += offsets[j];
if bitsj >= thresh[j] || done {
done = true;
psum += bitsj.min(cap[j]);
} else if bitsj >= ci << BITRES {
psum += ci << BITRES;
}
}
if psum > total {
hi = mid - 1;
} else {
lo = mid + 1;
}
if lo > hi {
break;
}
}
hi = lo;
lo -= 1;
for j in start..end {
let n = EBANDS[j + 1] - EBANDS[j];
let mut bits1j = (ci * n * (ALLOC[lo as usize][j] as i32)) << lmi >> 2;
let mut bits2j = if hi >= nb_alloc { cap[j] } else { (ci * n * (ALLOC[hi as usize][j] as i32)) << lmi >> 2 };
if bits1j > 0 {
bits1j = (bits1j + trim_offset[j]).max(0);
}
if bits2j > 0 {
bits2j = (bits2j + trim_offset[j]).max(0);
}
if lo > 0 {
bits1j += offsets[j];
}
bits2j += offsets[j];
if offsets[j] > 0 {
skip_start = j;
}
bits2j = (bits2j - bits1j).max(0);
bits1[j] = bits1j;
bits2[j] = bits2j;
}
let crate::opus::rate_common::Bracket { skip_start, bits1, bits2, thresh, total, skip_rsv, intensity_rsv, dual_stereo_rsv } =
crate::opus::rate_common::bracket(start, end, offsets, cap, alloc_trim, total, c, lm);
interp_bits2pulses(InterpPulsesInput {
mode: m,
start,
@@ -14,6 +14,7 @@ pub const MAX_LM: usize = 3;
pub const PREEMPH: f32 = 0.850_006_1;
/// Static allocation table (Table 57), indexed `[quality][band]`, in 1/32 bit per MDCT bin.
#[cfg(not(feature = "opus-encode"))]
pub const ALLOC: [[u8; NB_EBANDS]; 11] = transpose([
[0, 90, 110, 118, 126, 134, 144, 152, 162, 172, 200],
[0, 80, 100, 110, 119, 127, 137, 145, 155, 165, 200],
@@ -38,6 +39,7 @@ pub const ALLOC: [[u8; NB_EBANDS]; 11] = transpose([
[0, 0, 0, 0, 0, 1, 1, 1, 1, 20, 104],
]);
#[cfg(not(feature = "opus-encode"))]
const fn transpose(t: [[u8; 11]; NB_EBANDS]) -> [[u8; NB_EBANDS]; 11] {
let mut out = [[0u8; NB_EBANDS]; 11];
let mut b = 0;
+1 -19
View File
@@ -4,25 +4,7 @@
//! RFC 6716 Table 54 (and the integer delays used when no rate conversion is needed), so that the
//! SILK output lines up with the CELT layer in Hybrid mode.
/// Dot product with eight independent partial sums, so the additions pipeline and the loop
/// vectorises instead of waiting on one 4-cycle add chain. Rounds differently from a
/// sequential sum (the resampler is not normative).
#[inline]
fn dot8(a: &[f32], b: &[f32]) -> f32 {
let mut s = [0f32; 8];
let (ca, ra) = a.as_chunks::<8>();
let (cb, rb) = b.as_chunks::<8>();
for (x, y) in ca.iter().zip(cb) {
for l in 0..8 {
s[l] += x[l] * y[l];
}
}
let mut acc = ((s[0] + s[4]) + (s[1] + s[5])) + ((s[2] + s[6]) + (s[3] + s[7]));
for (x, y) in ra.iter().zip(rb) {
acc += x * y;
}
acc
}
use crate::opus::dot::dot8;
#[derive(Clone)]
pub struct Resampler {
+20
View File
@@ -0,0 +1,20 @@
//! Shared fixed-order FIR dot product.
/// Dot product with eight independent partial sums, which the compiler can vectorise (a single
/// running sum is bound by the latency of the float addition). The sums are combined pairwise.
#[inline]
pub(super) fn dot8(a: &[f32], b: &[f32]) -> f32 {
let mut s = [0f32; 8];
let (ca, ra) = a.as_chunks::<8>();
let (cb, rb) = b.as_chunks::<8>();
for (x, y) in ca.iter().zip(cb) {
for l in 0..8 {
s[l] += x[l] * y[l];
}
}
let mut acc = ((s[0] + s[4]) + (s[1] + s[5])) + ((s[2] + s[6]) + (s[3] + s[7]));
for (x, y) in ra.iter().zip(rb) {
acc += x * y;
}
acc
}
+282 -59
View File
@@ -8,7 +8,8 @@
use crate::opus::encoder::range::{BITRES, RangeEncoder, ilog};
use crate::opus::encoder::rate::{Mode, QTHETA_OFFSET, get_pulses};
use crate::opus::encoder::tables::{EBANDS, NB_EBANDS};
use crate::opus::encoder::tables::EBANDS;
use crate::opus::encoder::{CeltFrame, rate::Allocation};
pub const SPREAD_NORMAL: usize = 2;
@@ -55,7 +56,7 @@ fn exp_rotation1_inv(x: &mut [f32], len: usize, stride: usize, c: f32, s: f32) {
if len <= stride {
return;
}
if len >= 2 * stride + 1 {
if len > 2 * stride {
for i in 0..=len - 2 * stride - 1 {
let x1 = x[i];
let x2 = x[i + stride];
@@ -96,12 +97,24 @@ pub fn exp_rotation_inv(x: &mut [f32], len: usize, k: usize, spread: usize) {
}
}
/// Relative slack for the pulse-candidate filter in [`pvq_search`]: far above the f32 rounding of
/// the filter score (a few 1e-7), far below the spread of real scores.
const PVQ_SCORE_SLACK: f32 = 1e-5;
/// Greedy PVQ search: the integer vector `y` with `sum |y| = k` closest in direction to `x`.
pub fn pvq_search(x: &[f32], k: usize, y: &mut [i32]) {
let n = x.len();
y[..n].fill(0);
let abs: Vec<f32> = x.iter().map(|v| v.abs()).collect();
let sum: f32 = abs.iter().sum();
// `abs`, `dy` (2 y + 1, infinite in the padding) and the per-pass scores `score`, each padded to
// whole 8-lane chunks.
let np = n.next_multiple_of(8);
let mut buf = vec![0f32; 3 * np];
let (abs, rest) = buf.split_at_mut(np);
let (dy, score) = rest.split_at_mut(np);
for (a, v) in abs.iter_mut().zip(x) {
*a = v.abs();
}
let sum: f32 = abs[..n].iter().sum();
if !sum.is_finite() || sum <= 1e-15 {
y[0] = k as i32;
return;
@@ -113,30 +126,69 @@ pub fn pvq_search(x: &[f32], k: usize, y: &mut [i32]) {
// Pre-project onto the pyramid (rounding down) and place the rest greedily.
let r = (k as f32 - 1.0) / sum;
for j in 0..n {
let p = (abs[j] * r).floor() as i32;
// Non-negative and at most k, so the truncating cast is the floor.
let p = (abs[j] * r) as i32;
y[j] = p;
placed += p as usize;
xy += abs[j] * p as f32;
yy += (p * p) as f32;
}
}
for j in 0..np {
dy[j] = if j < n { 2.0 * y[j] as f32 + 1.0 } else { f32::INFINITY };
}
while placed < k {
// Vectorisable scores (xy + |x_j|)^2 / (yy + 2 y_j + 1) and their maximum.
for ((sc, &a), &d) in score.iter_mut().zip(abs.iter()).zip(dy.iter()) {
let t = xy + a;
*sc = t * t / (yy + d);
}
let mut lane_max = [0f32; 8];
for c in score.as_chunks::<8>().0 {
for i in 0..8 {
lane_max[i] = if c[i] > lane_max[i] { c[i] } else { lane_max[i] };
}
}
let top = lane_max.iter().fold(0f32, |m, &v| if v > m { v } else { m });
// The exact cross-multiplied test below, in index order with the first maximum winning, only
// matters for entries within rounding distance of the top score: every other entry is beaten
// by the top one whenever it is reached and never beats it afterwards. Running the test on
// those alone therefore picks the same pulse as running it on all of them.
let filter = top > 1e-30 && top.is_finite();
let lo = top * (1.0 - PVQ_SCORE_SLACK);
// Usually exactly one entry qualifies; its index falls out of a lane-wise count.
let mut count = [0u32; 8];
let mut index = [0u32; 8];
for (ci, c) in score.as_chunks::<8>().0.iter().enumerate() {
for i in 0..8 {
let hit = u32::from(c[i] >= lo);
count[i] += hit;
index[i] += hit * (ci * 8 + i) as u32;
}
}
let mut best = 0usize;
let mut best_num = -1f32;
let mut best_den = 1f32;
for j in 0..n {
let num = xy + abs[j];
let num = num * num;
let den = yy + 2.0 * y[j] as f32 + 1.0;
if num * best_den > best_num * den {
best_num = num;
best_den = den;
best = j;
if filter && count.iter().sum::<u32>() == 1 {
best = index.iter().sum::<u32>() as usize;
} else {
let mut best_num = -1f32;
let mut best_den = 1f32;
for j in 0..n {
if !filter || score[j] >= lo {
let num = xy + abs[j];
let num = num * num;
let den = yy + 2.0 * y[j] as f32 + 1.0;
if num * best_den > best_num * den {
best_num = num;
best_den = den;
best = j;
}
}
}
}
xy += abs[best];
yy += 2.0 * y[best] as f32 + 1.0;
y[best] += 1;
dy[best] = 2.0 * y[best] as f32 + 1.0;
placed += 1;
}
for j in 0..n {
@@ -146,25 +198,45 @@ pub fn pvq_search(x: &[f32], k: usize, y: &mut [i32]) {
}
}
/// Encodes the PVQ codeword `y` (`sum |y| = k`) as the index the RFC 6716 §4.3.4.2 decoder maps
/// back to `y`.
pub fn encode_pulses(y: &[i32], k: usize, enc: &mut RangeEncoder, v: &mut Vec<u64>) {
let n = y.len();
let w = k + 1;
v.clear();
v.resize((n + 1) * w, 0);
/// Largest band width and pulse count the encoder codes (176 coefficients, `get_pulses(40)` = 128).
const PVQ_MAX_N: usize = 176;
const PVQ_MAX_K: usize = 128;
/// Row-major `V(n, k)` for `n <= max_n`, `k <= max_k` with row stride `max_k + 1`, saturated at
/// `u32::MAX` (a codebook that large is never coded, see `rate::fits_in32`).
fn build_pvq_table(max_n: usize, max_k: usize) -> Vec<u32> {
let w = max_k + 1;
let mut v = vec![0u32; (max_n + 1) * w];
v[0] = 1;
for nn in 1..=n {
for nn in 1..=max_n {
v[nn * w] = 1;
for kk in 1..=k {
let a = v[(nn - 1) * w + kk];
let b = v[nn * w + kk - 1];
let c = v[(nn - 1) * w + kk - 1];
v[nn * w + kk] = a.saturating_add(b).saturating_add(c);
for kk in 1..=max_k {
let sum = v[(nn - 1) * w + kk] as u64 + v[nn * w + kk - 1] as u64 + v[(nn - 1) * w + kk - 1] as u64;
v[nn * w + kk] = sum.min(u32::MAX as u64) as u32;
}
}
let total = v[n * w + k];
let vv = |nn: usize, kx: usize| v[nn * w + kx];
v
}
fn pvq_table() -> &'static [u32] {
static TABLE: std::sync::OnceLock<Vec<u32>> = std::sync::OnceLock::new();
TABLE.get_or_init(|| build_pvq_table(PVQ_MAX_N, PVQ_MAX_K))
}
/// Encodes the PVQ codeword `y` (`sum |y| = k`) as the index the RFC 6716 §4.3.4.2 decoder maps
/// back to `y`.
pub fn encode_pulses(y: &[i32], k: usize, enc: &mut RangeEncoder) {
let n = y.len();
// Shapes outside the coded range (never produced by the band layout) get a local table.
let local;
let (v, w) = if n <= PVQ_MAX_N && k <= PVQ_MAX_K {
(pvq_table(), PVQ_MAX_K + 1)
} else {
local = build_pvq_table(n, k);
(&local[..], k + 1)
};
let row = |nn: usize| &v[nn * w..(nn + 1) * w];
let total = row(n)[k] as u64;
let mut index = 0u64;
let mut kk = k;
for j in 0..n {
@@ -173,10 +245,11 @@ pub fn encode_pulses(y: &[i32], k: usize, enc: &mut RangeEncoder, v: &mut Vec<u6
}
let rem = n - j;
let t = y[j].unsigned_abs() as usize;
let below = row(rem - 1);
// Codewords with |y_j| = t start at sum_{m < kk - t} V(rem-1, m) within their sign half.
let mut base: u64 = (0..kk - t).map(|m| vv(rem - 1, m)).sum();
let mut base: u64 = below[..kk - t].iter().map(|&x| x as u64).sum();
if y[j] < 0 {
base += (vv(rem - 1, kk) + vv(rem, kk)) / 2;
base += (below[kk] as u64 + row(rem)[kk] as u64) / 2;
}
index += base;
kk -= t;
@@ -193,7 +266,6 @@ pub struct BandEnc<'m, 'e> {
pub i: usize,
pub spread: usize,
pub remaining_bits: i32,
pvq_v: Vec<u64>,
iy: Vec<i32>,
tmp: Vec<f32>,
}
@@ -217,7 +289,7 @@ impl BandEnc<'_, '_> {
let q = qn as u32;
let half = q >> 1;
let ft = (half + 1) * (half + 1);
let (fl, fs) = if it <= half { (it * (it + 1) >> 1, it + 1) } else { (ft - ((q + 1 - it) * (q + 2 - it) >> 1), q + 1 - it) };
let (fl, fs) = if it <= half { ((it * (it + 1)) >> 1, it + 1) } else { (ft - (((q + 1 - it) * (q + 2 - it)) >> 1), q + 1 - it) };
self.enc.encode(fl, fl + fs, ft);
itheta = ((it * 16384) / q) as i32;
}
@@ -287,36 +359,29 @@ impl BandEnc<'_, '_> {
iy.clear();
iy.resize(n, 0);
pvq_search(&tmp, k, &mut iy);
encode_pulses(&iy, k, self.enc, &mut self.pvq_v);
encode_pulses(&iy, k, self.enc);
self.iy = iy;
self.tmp = tmp;
}
}
}
/// Codes all band shapes (`quant_all_bands`, encoder side, long blocks). `x` holds `c` channels
/// of `n` normalised MDCT coefficients each.
#[allow(clippy::too_many_arguments)]
pub fn quant_all_bands(
m: &Mode,
start: usize,
end: usize,
x: &[f32],
n_total: usize,
c: usize,
pulses: &[i32; NB_EBANDS],
spread: usize,
dual_stereo: bool,
intensity: usize,
total_bits: i32,
mut balance: i32,
enc: &mut RangeEncoder,
lm: usize,
coded_bands: usize,
) {
/// Shape-coding controls, independent of the selected band allocation.
pub struct BandCoding {
pub spread: usize,
pub total_bits: i32,
}
/// Codes all band shapes (`quant_all_bands`, encoder side, long blocks). `x` holds
/// `frame.channels` channels of `n_total` normalised MDCT coefficients each.
pub fn quant_all_bands(m: &Mode, frame: CeltFrame, x: &[f32], n_total: usize, allocation: &Allocation, coding: BandCoding, enc: &mut RangeEncoder) {
let CeltFrame { start, end, channels: c, lm } = frame;
let Allocation { pulses, dual_stereo, intensity, coded_bands, balance, .. } = allocation;
let (dual_stereo, intensity, coded_bands, mut balance) = (*dual_stereo, *intensity, *coded_bands, *balance);
let BandCoding { spread, total_bits } = coding;
let mm = 1usize << lm;
debug_assert!(c == 1 || dual_stereo || intensity <= start, "stereo frames are coded as dual stereo");
let mut ctx = BandEnc { m, enc, i: 0, spread, remaining_bits: 0, pvq_v: Vec::new(), iy: Vec::new(), tmp: Vec::new() };
let mut ctx = BandEnc { m, enc, i: 0, spread, remaining_bits: 0, iy: Vec::new(), tmp: Vec::new() };
for i in start..end {
ctx.i = i;
let xo = mm * EBANDS[i] as usize;
@@ -362,7 +427,7 @@ mod tests {
x[i + stride] = c * x2 + s * x1;
x[i] = c * x1 + ms * x2;
}
if len >= 2 * stride + 1 {
if len > 2 * stride {
for i in (0..=len - 2 * stride - 1).rev() {
let x1 = x[i];
let x2 = x[i + stride];
@@ -466,12 +531,11 @@ mod tests {
#[test]
fn pvq_index_roundtrip_exhaustive() {
let mut v = Vec::new();
for n in 1..6usize {
for k in 1..6usize {
for y in all_codewords(n, k) {
let mut e = RangeEncoder::new();
encode_pulses(&y, k, &mut e, &mut v);
encode_pulses(&y, k, &mut e);
let buf = e.done(16);
let mut d = RangeDecoder::new(&buf);
assert_eq!(decode_pulses(n, k, &mut d), y, "n={n} k={k}");
@@ -480,6 +544,165 @@ mod tests {
}
}
/// The per-call table encoder this module used before the shared table.
fn encode_pulses_reference(y: &[i32], k: usize, enc: &mut RangeEncoder) {
let n = y.len();
let w = k + 1;
let mut v = vec![0u64; (n + 1) * w];
v[0] = 1;
for nn in 1..=n {
v[nn * w] = 1;
for kk in 1..=k {
let a = v[(nn - 1) * w + kk];
let b = v[nn * w + kk - 1];
let c = v[(nn - 1) * w + kk - 1];
v[nn * w + kk] = a.saturating_add(b).saturating_add(c);
}
}
let total = v[n * w + k];
let vv = |nn: usize, kx: usize| v[nn * w + kx];
let mut index = 0u64;
let mut kk = k;
for j in 0..n {
if kk == 0 {
break;
}
let rem = n - j;
let t = y[j].unsigned_abs() as usize;
let mut base: u64 = (0..kk - t).map(|m| vv(rem - 1, m)).sum();
if y[j] < 0 {
base += (vv(rem - 1, kk) + vv(rem, kk)) / 2;
}
index += base;
kk -= t;
}
if total >= 2 {
enc.uint(index as u32, total as u32);
}
}
#[test]
fn pvq_table_encode_matches_per_call_table() {
let mut seed = 0x9E37_79B9_7F4A_7C15u64;
let mut next = move |m: u64| {
seed ^= seed << 13;
seed ^= seed >> 7;
seed ^= seed << 17;
seed % m
};
let mut checked = 0;
for n in (1..=PVQ_MAX_N).step_by(5).chain([PVQ_MAX_N]) {
for k in (1..=PVQ_MAX_K).step_by(3).chain([PVQ_MAX_K]) {
if crate::opus::encoder::rate::pvq_v(n, k) > u32::MAX as u128 {
continue;
}
for _ in 0..4 {
let mut y = vec![0i32; n];
for _ in 0..k {
let at = next(n as u64) as usize;
y[at] += if next(2) == 0 { 1 } else { -1 };
}
// Opposite pulses cancel; top up so that sum |y| = k again.
let mut have: usize = y.iter().map(|v| v.unsigned_abs() as usize).sum();
while have < k {
let at = next(n as u64) as usize;
y[at] += if y[at] < 0 { -1 } else { 1 };
have += 1;
}
let (mut a, mut b) = (RangeEncoder::new(), RangeEncoder::new());
encode_pulses(&y, k, &mut a);
encode_pulses_reference(&y, k, &mut b);
assert_eq!(a.done(16), b.done(16), "n={n} k={k}");
checked += 1;
}
}
}
assert!(checked > 100, "{checked}");
}
/// The scalar greedy search the vectorised one replaced.
fn pvq_search_ref(x: &[f32], k: usize, y: &mut [i32]) {
let n = x.len();
y[..n].fill(0);
let abs: Vec<f32> = x.iter().map(|v| v.abs()).collect();
let sum: f32 = abs.iter().sum();
if !sum.is_finite() || sum <= 1e-15 {
y[0] = k as i32;
return;
}
let mut placed = 0usize;
let mut xy = 0f32;
let mut yy = 0f32;
if k > n / 2 {
let r = (k as f32 - 1.0) / sum;
for j in 0..n {
let p = (abs[j] * r).floor() as i32;
y[j] = p;
placed += p as usize;
xy += abs[j] * p as f32;
yy += (p * p) as f32;
}
}
while placed < k {
let mut best = 0usize;
let mut best_num = -1f32;
let mut best_den = 1f32;
for j in 0..n {
let num = xy + abs[j];
let num = num * num;
let den = yy + 2.0 * y[j] as f32 + 1.0;
if num * best_den > best_num * den {
best_num = num;
best_den = den;
best = j;
}
}
xy += abs[best];
yy += 2.0 * y[best] as f32 + 1.0;
y[best] += 1;
placed += 1;
}
for j in 0..n {
if x[j] < 0.0 {
y[j] = -y[j];
}
}
}
#[test]
fn pvq_search_matches_scalar_reference() {
let mut state = 0x9e3779b97f4a7c15u64;
let mut rnd = move || {
state ^= state << 13;
state ^= state >> 7;
state ^= state << 17;
(state >> 40) as f32 / (1u64 << 24) as f32 * 2.0 - 1.0
};
let mut a = vec![0i32; 200];
let mut b = vec![0i32; 200];
let mut cases = 0;
for round in 0..6000 {
let n = 1 + (round * 37 + (rnd().abs() * 176.0) as usize) % 176;
let k = 1 + (rnd().abs() * 127.0) as usize;
let scale = [1.0f32, 1e-9, 1e6, 3e-3][round % 4];
let x: Vec<f32> = (0..n)
.map(|_| match round % 6 {
0 => rnd(),
1 => if rnd() > 0.8 { rnd() } else { 0.0 },
2 => (rnd() * 4.0).round() / 4.0,
3 => if rnd() > 0.0 { 1.0 } else { -1.0 },
4 => rnd().powi(5),
_ => if rnd() > 0.95 { 3.0 * rnd() } else { 1e-4 * rnd() },
} * scale)
.collect();
pvq_search(&x, k, &mut a);
pvq_search_ref(&x, k, &mut b);
assert_eq!(a[..n], b[..n], "n={n} k={k} round={round}");
cases += 1;
}
assert_eq!(cases, 6000);
}
#[test]
fn pvq_search_finds_good_direction() {
let x: Vec<f32> = (0..32).map(|i| ((i as f32) * 0.7).sin()).collect();
+10 -15
View File
@@ -4,8 +4,9 @@
//! The quantised energies are updated with exactly the decoder's arithmetic so the prediction
//! state never drifts between encoder and decoder.
use crate::opus::encoder::CeltFrame;
use crate::opus::encoder::range::RangeEncoder;
use crate::opus::encoder::rate::MAX_FINE_BITS;
use crate::opus::encoder::rate::{Allocation, MAX_FINE_BITS};
use crate::opus::encoder::tables::{BETA_COEF, BETA_INTRA, E_PROB_MODEL, NB_EBANDS, PRED_COEF, SMALL_ENERGY_ICDF};
const LAPLACE_MINP: u32 = 1;
@@ -56,18 +57,15 @@ pub fn laplace_encode(enc: &mut RangeEncoder, value: i32, mut fs: u32, decay: u3
/// `quant_coarse_energy` for one prediction mode. `e` holds the target log2 energies (relative
/// to `E_MEANS`), `old_e` the quantised energies, updated in place. `budget` is the frame size in
/// bits.
#[allow(clippy::too_many_arguments)]
pub fn quant_coarse_energy(
start: usize,
end: usize,
frame: CeltFrame,
e: &[f32; 2 * NB_EBANDS],
old_e: &mut [f32; 2 * NB_EBANDS],
intra: bool,
enc: &mut RangeEncoder,
c: usize,
lm: usize,
budget: i32,
) {
let CeltFrame { start, end, channels: c, lm } = frame;
let prob = &E_PROB_MODEL[lm][intra as usize];
let (coef, beta) = if intra { (0.0, BETA_INTRA) } else { (PRED_COEF[lm], BETA_COEF[lm]) };
let mut prev = [0f32; 2];
@@ -112,14 +110,13 @@ pub fn quant_coarse_energy(
/// `quant_fine_energy`: raw bits refining each band's quantised energy.
pub fn quant_fine_energy(
start: usize,
end: usize,
frame: CeltFrame,
e: &[f32; 2 * NB_EBANDS],
old_e: &mut [f32; 2 * NB_EBANDS],
fine_quant: &[i32; NB_EBANDS],
enc: &mut RangeEncoder,
c: usize,
) {
let CeltFrame { start, end, channels: c, .. } = frame;
for i in start..end {
let fq = fine_quant[i];
if fq <= 0 {
@@ -139,18 +136,16 @@ pub fn quant_fine_energy(
/// `quant_energy_finalise`: spends the bits left at the end of the frame on one more bit of
/// energy resolution per band, in priority order.
#[allow(clippy::too_many_arguments)]
pub fn quant_energy_finalise(
start: usize,
end: usize,
frame: CeltFrame,
e: &[f32; 2 * NB_EBANDS],
old_e: &mut [f32; 2 * NB_EBANDS],
fine_quant: &[i32; NB_EBANDS],
fine_priority: &[i32; NB_EBANDS],
allocation: &Allocation,
mut bits_left: i32,
enc: &mut RangeEncoder,
c: usize,
) {
let CeltFrame { start, end, channels: c, .. } = frame;
let Allocation { fine_quant, fine_priority, .. } = allocation;
for prio in 0..2 {
let mut i = start;
while i < end && bits_left >= c as i32 {
+26 -78
View File
@@ -9,84 +9,7 @@
use crate::opus::encoder::tables::OVERLAP;
#[derive(Clone, Copy, Default, Debug)]
pub struct Cpx {
pub re: f32,
pub im: f32,
}
impl Cpx {
#[inline]
fn mul(self, o: Cpx) -> Cpx {
Cpx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re }
}
#[inline]
fn add(self, o: Cpx) -> Cpx {
Cpx { re: self.re + o.re, im: self.im + o.im }
}
}
/// Mixed-radix (2, 3, 4, 5) forward complex FFT, unscaled (decimation in time, recursive).
pub struct Fft {
n: usize,
factors: Vec<usize>,
twiddle: Vec<Cpx>,
}
impl Fft {
pub fn new(n: usize) -> Fft {
let mut factors = Vec::new();
let mut m = n;
for p in [4usize, 2, 3, 5] {
while m.is_multiple_of(p) {
factors.push(p);
m /= p;
}
}
assert_eq!(m, 1, "unsupported FFT size {n}");
let twiddle = (0..n)
.map(|k| {
let ph = -2.0 * std::f64::consts::PI * k as f64 / n as f64;
Cpx { re: ph.cos() as f32, im: ph.sin() as f32 }
})
.collect();
Fft { n, factors, twiddle }
}
pub fn process(&self, data: &mut [Cpx], scratch: &mut Vec<Cpx>) {
scratch.clear();
scratch.extend_from_slice(&data[..self.n]);
self.rec(&mut data[..self.n], scratch, 1, self.n, 0, 1);
}
fn rec(&self, out: &mut [Cpx], inp: &[Cpx], in_stride: usize, n: usize, fi: usize, tw_stride: usize) {
let p = self.factors[fi];
let m = n / p;
if m == 1 {
for (i, o) in out.iter_mut().enumerate().take(p) {
*o = inp[i * in_stride];
}
} else {
for q in 0..p {
self.rec(&mut out[q * m..(q + 1) * m], &inp[q * in_stride..], in_stride * p, m, fi + 1, tw_stride * p);
}
}
let big = self.n;
let mut t = [Cpx::default(); 5];
for k in 0..m {
for (q, tq) in t.iter_mut().enumerate().take(p) {
*tq = out[q * m + k].mul(self.twiddle[(q * k * tw_stride) % big]);
}
for q2 in 0..p {
let mut acc = Cpx::default();
for (q, tq) in t.iter().enumerate().take(p) {
acc = acc.add(tq.mul(self.twiddle[((q * q2) % p) * (big / p)]));
}
out[q2 * m + k] = acc;
}
}
}
}
use crate::opus::fft::{Cpx, Fft};
/// Forward MDCT producing `n` coefficients from a block of `n + OVERLAP` samples.
pub struct Mdct {
@@ -199,6 +122,31 @@ mod tests {
.collect()
}
#[test]
fn fft_matches_dft() {
// Every radix combination, including the 480-point size of the 20 ms frame.
for &n in &[2usize, 3, 4, 5, 6, 8, 12, 15, 16, 20, 24, 30, 48, 60, 120, 240, 480] {
let fft = Fft::new(n);
let x: Vec<Cpx> = (0..n).map(|i| Cpx { re: ((i * 37 % 101) as f32 - 50.0) / 7.0, im: ((i * 53 % 89) as f32 - 44.0) / 9.0 }).collect();
let mut y = x.clone();
fft.process(&mut y, &mut Vec::new());
for k in 0..n {
let (mut re, mut im) = (0f64, 0f64);
for (j, v) in x.iter().enumerate() {
let ph = -2.0 * std::f64::consts::PI * ((j * k) % n) as f64 / n as f64;
re += v.re as f64 * ph.cos() - v.im as f64 * ph.sin();
im += v.re as f64 * ph.sin() + v.im as f64 * ph.cos();
}
assert!(
(y[k].re as f64 - re).abs() < 2e-3 && (y[k].im as f64 - im).abs() < 2e-3,
"n={n} k={k}: ({}, {}) vs ({re}, {im})",
y[k].re,
y[k].im
);
}
}
}
#[test]
fn matches_direct_formula() {
for &n in &[240usize, 960] {
+36 -33
View File
@@ -10,8 +10,9 @@
//! above in the same range-coded frame; constant packet size.
//! - **CELT** (fullband): MDCT transform coding; constant packet size.
//!
//! From EffectCraft's `effectcraft-opusenc` (storytold/effectcraft@c618429). Public items keep their
//! names, so EffectCraft can re-export this module.
//! From EffectCraft's `effectcraft-opusenc` (storytold/effectcraft@c618429), with its later speed-ups
//! and CELT stage refactor up to storytold/effectcraft@d6c9ad66. Public items keep their names, so
//! EffectCraft can re-export this module.
//!
//! ```
//! # #[cfg(feature = "opus-encode")] {
@@ -26,6 +27,7 @@
//! # }
//! ```
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
// The bit-allocation code mirrors the normative integer arithmetic; keep C-like shift expressions.
#![allow(clippy::precedence, clippy::int_plus_one)]
@@ -36,19 +38,28 @@ mod range;
mod rate;
mod resample;
mod silk;
mod tables;
pub(super) mod tables;
use std::sync::OnceLock;
use bands::{SPREAD_NORMAL, quant_all_bands};
use bands::{BandCoding, SPREAD_NORMAL, quant_all_bands};
use energy::{quant_coarse_energy, quant_energy_finalise, quant_fine_energy};
use mdct::Mdct;
use range::{BITRES, RangeEncoder};
use rate::{Mode as CeltMode, compute_allocation};
use rate::{AllocationInput, Mode as CeltMode, compute_allocation};
use resample::Downsampler;
use silk::SilkEncoder;
use tables::{E_MEANS, EBANDS, NB_EBANDS, OVERLAP, PREEMPH, SPREAD_ICDF, TF_SELECT_TABLE, TRIM_ICDF};
/// Band range, channel count and transform size shared by CELT coding stages.
#[derive(Clone, Copy)]
struct CeltFrame {
start: usize,
end: usize,
channels: usize,
lm: usize,
}
/// Samples per channel in one 20 ms frame at 48 kHz.
const N: usize = 960;
/// LM of a 20 ms frame (8 short blocks).
@@ -338,7 +349,7 @@ impl Encoder {
Mode::Celt => {
let (log_e, silence) = self.celt_analysis(pcm);
let len = self.frame_bytes;
packet.extend_from_slice(&self.encode_celt(RangeEncoder::new(), len, 0, NB_EBANDS, &log_e, silence));
packet.extend_from_slice(&self.encode_celt(RangeEncoder::new(), len, 0..NB_EBANDS, &log_e, silence));
}
Mode::Silk => {
let x = self.silk_input(pcm);
@@ -368,7 +379,7 @@ impl Encoder {
}
let (log_e, _) = self.celt_analysis(pcm);
let end = if self.bandwidth == Bandwidth::SuperWideband { 19 } else { NB_EBANDS };
packet.extend_from_slice(&self.encode_celt(enc, len, HYBRID_START_BAND, end, &log_e, false));
packet.extend_from_slice(&self.encode_celt(enc, len, HYBRID_START_BAND..end, &log_e, false));
}
}
Ok(packet)
@@ -430,10 +441,18 @@ impl Encoder {
/// Codes one CELT frame (RFC 6716 §4.3, in bitstream order) of `len` bytes into `enc`
/// (which already holds the SILK frame in hybrid mode), coding bands `start..end`, and
/// finalises the frame.
#[allow(clippy::too_many_arguments)]
fn encode_celt(&mut self, mut enc: RangeEncoder, len: usize, start: usize, end: usize, log_e: &[f32; 2 * NB_EBANDS], silence: bool) -> Vec<u8> {
fn encode_celt(
&mut self,
mut enc: RangeEncoder,
len: usize,
bands: std::ops::Range<usize>,
log_e: &[f32; 2 * NB_EBANDS],
silence: bool,
) -> Vec<u8> {
let m = celt_mode();
let c = self.channels;
let frame = CeltFrame { start: bands.start, end: bands.end, channels: c, lm: LM };
let CeltFrame { start, end, .. } = frame;
if c == 1 {
for i in 0..NB_EBANDS {
self.old_band_e[i] = self.old_band_e[i].max(self.old_band_e[NB_EBANDS + i]);
@@ -462,10 +481,10 @@ impl Encoder {
let mut enc_intra = enc.clone();
let mut old_intra = self.old_band_e;
enc_intra.bit_logp(true, 3);
quant_coarse_energy(start, end, log_e, &mut old_intra, true, &mut enc_intra, c, LM, total_bits_raw);
quant_coarse_energy(frame, log_e, &mut old_intra, true, &mut enc_intra, total_bits_raw);
enc.bit_logp(false, 3);
let mut old_inter = self.old_band_e;
quant_coarse_energy(start, end, log_e, &mut old_inter, false, &mut enc, c, LM, total_bits_raw);
quant_coarse_energy(frame, log_e, &mut old_inter, false, &mut enc, total_bits_raw);
if enc_intra.tell_frac() < enc.tell_frac() {
enc = enc_intra;
self.old_band_e = old_intra;
@@ -473,14 +492,14 @@ impl Encoder {
self.old_band_e = old_inter;
}
} else {
quant_coarse_energy(start, end, log_e, &mut self.old_band_e, false, &mut enc, c, LM, total_bits_raw);
quant_coarse_energy(frame, log_e, &mut self.old_band_e, false, &mut enc, total_bits_raw);
}
// TF resolution: no changes.
{
let mut budget = total_bits_raw;
let mut tell = enc.tell();
let mut logp = 4;
let tf_select_rsv = LM > 0 && tell + logp + 1 <= budget;
let tf_select_rsv = LM > 0 && tell + logp < budget;
budget -= tf_select_rsv as i32;
for _ in start..end {
if tell + logp <= budget {
@@ -512,27 +531,11 @@ impl Encoder {
enc.icdf(alloc_trim as usize, &TRIM_ICDF, 7);
}
let bits = (total_bits_raw << BITRES) - enc.tell_frac() - 1;
let alloc = compute_allocation(m, start, end, &offsets, &cap, alloc_trim, bits, c, LM, &mut enc);
quant_fine_energy(start, end, log_e, &mut self.old_band_e, &alloc.fine_quant, &mut enc, c);
quant_all_bands(
m,
start,
end,
&self.freq,
N,
c,
&alloc.pulses,
SPREAD_NORMAL,
alloc.dual_stereo,
alloc.intensity,
total_bits_raw << BITRES,
alloc.balance,
&mut enc,
LM,
alloc.coded_bands,
);
let alloc = compute_allocation(m, frame, AllocationInput { offsets: &offsets, cap: &cap, trim: alloc_trim, bits }, &mut enc);
quant_fine_energy(frame, log_e, &mut self.old_band_e, &alloc.fine_quant, &mut enc);
quant_all_bands(m, frame, &self.freq, N, &alloc, BandCoding { spread: SPREAD_NORMAL, total_bits: total_bits_raw << BITRES }, &mut enc);
let bits_left = total_bits_raw - enc.tell();
quant_energy_finalise(start, end, log_e, &mut self.old_band_e, &alloc.fine_quant, &alloc.fine_priority, bits_left, &mut enc, c);
quant_energy_finalise(frame, log_e, &mut self.old_band_e, &alloc, bits_left, &mut enc);
debug_assert!(enc.tell() <= total_bits_raw, "frame overflow: {} > {}", enc.tell(), total_bits_raw);
if c == 1 {
let (a, b) = self.old_band_e.split_at_mut(NB_EBANDS);
+45 -363
View File
@@ -4,254 +4,18 @@
//! spec-derived `filmcraft-opus` decoder (first-party, MIT OR Apache-2.0) step by step; the only
//! difference is that the encoder *writes* the band-skip, intensity and dual-stereo symbols.
use crate::opus::encoder::range::{BITRES, RangeEncoder, ilog};
use crate::opus::encoder::tables::{ALLOC, EBANDS, LOG2_FRAC_TABLE, MAX_LM, NB_EBANDS};
use crate::opus::encoder::CeltFrame;
use crate::opus::encoder::range::{BITRES, RangeEncoder};
use crate::opus::encoder::tables::{EBANDS, LOG2_FRAC_TABLE, NB_EBANDS};
const MAX_PSEUDO: i32 = 40;
const LOG_MAX_PSEUDO: i32 = 6;
#[cfg(test)]
pub use crate::opus::rate_common::pvq_v;
pub use crate::opus::rate_common::{Mode, get_pulses};
pub const MAX_FINE_BITS: i32 = 8;
const FINE_OFFSET: i32 = 21;
pub const QTHETA_OFFSET: i32 = 4;
pub const QTHETA_OFFSET_TWOPHASE: i32 = 16;
const ALLOC_STEPS: i32 = 6;
/// Number of pulses represented by pseudo-pulse index `i`.
pub fn get_pulses(i: i32) -> i32 {
if i < 8 { i } else { (8 + (i & 7)) << ((i >> 3) - 1) }
}
/// Conservative (rounded up) log2 of `val` with `frac` fractional bits.
pub fn log2_frac(mut val: u32, mut frac: u32) -> i32 {
let mut l = ilog(val);
if val & val.wrapping_sub(1) != 0 {
if l > 16 {
val = ((val - 1) >> (l - 16)) + 1;
} else {
val <<= 16 - l;
}
let mut l = (l - 1) << frac;
loop {
let b = (val >> 16) as i32;
l += b << frac;
val = (val + b as u32) >> b;
val = (val * val + 0x7FFF) >> 15;
if frac == 0 {
break;
}
frac -= 1;
}
l + (val > 0x8000) as i32
} else {
l -= 1;
l << frac
}
}
/// PVQ codebook size V(N, K) (saturating far above 2^32).
pub fn pvq_v(n: usize, k: usize) -> u128 {
if k == 0 {
return 1;
}
if n == 0 {
return 0;
}
let mut row = vec![0u128; k + 1];
row[0] = 1;
for _ in 0..n {
let mut prev_diag = row[0];
for kk in 1..=k {
let up = row[kk];
let v = up.saturating_add(row[kk - 1]).saturating_add(prev_diag);
prev_diag = up;
row[kk] = v.min(u128::MAX >> 8);
}
row[0] = 1;
}
row[k]
}
fn fits_in32(n: usize, k: i32) -> bool {
pvq_v(n, k as usize) <= u32::MAX as u128
}
/// Precomputed per-mode data.
pub struct Mode {
/// log2 of band width in 1/8 bits.
pub log_n: [i32; NB_EBANDS],
cache_index: Vec<i16>,
cache_bits: Vec<u8>,
caps: Vec<u8>,
}
impl Mode {
pub fn new() -> Mode {
let mut log_n = [0i32; NB_EBANDS];
for (i, l) in log_n.iter_mut().enumerate() {
*l = log2_frac((EBANDS[i + 1] - EBANDS[i]) as u32, BITRES);
}
let (cache_index, cache_bits) = compute_pulse_cache(MAX_LM as i32);
let mut m = Mode { log_n, cache_index, cache_bits, caps: Vec::new() };
m.caps = compute_caps(&m);
m
}
#[inline]
pub fn cache(&self, lm: i32, band: usize) -> &[u8] {
let idx = self.cache_index[((lm + 1) as usize) * NB_EBANDS + band];
&self.cache_bits[idx.max(0) as usize..]
}
pub fn bits2pulses(&self, band: usize, lm: i32, bits: i32) -> i32 {
let cache = self.cache(lm, band);
let mut lo = 0i32;
let mut hi = cache[0] as i32;
let bits = bits - 1;
for _ in 0..LOG_MAX_PSEUDO {
let mid = (lo + hi + 1) >> 1;
if cache[mid as usize] as i32 >= bits {
hi = mid;
} else {
lo = mid;
}
}
let lo_bits = if lo == 0 { -1 } else { cache[lo as usize] as i32 };
if bits - lo_bits <= cache[hi as usize] as i32 - bits { lo } else { hi }
}
pub fn pulses2bits(&self, band: usize, lm: i32, pulses: i32) -> i32 {
if pulses == 0 { 0 } else { self.cache(lm, band)[pulses as usize] as i32 + 1 }
}
/// Per-band allocation caps for this frame (`init_caps`).
pub fn init_caps(&self, lm: usize, c: usize) -> [i32; NB_EBANDS] {
let mut cap = [0i32; NB_EBANDS];
for (i, cp) in cap.iter_mut().enumerate() {
let n = (EBANDS[i + 1] - EBANDS[i]) << lm;
*cp = (self.caps[NB_EBANDS * (2 * lm + c - 1) + i] as i32 + 64) * c as i32 * n >> 2;
}
cap
}
}
fn compute_pulse_cache(lm_max: i32) -> (Vec<i16>, Vec<u8>) {
let nb = NB_EBANDS;
let rows = (lm_max + 2) as usize;
let mut index = vec![-1i16; nb * rows];
let mut entries: Vec<(usize, i32, usize)> = Vec::new();
let mut curr = 0usize;
for i in 0..rows {
for j in 0..nb {
let n = (((EBANDS[j + 1] - EBANDS[j]) << i) >> 1) as usize;
index[i * nb + j] = -1;
'search: for k in 0..=i {
for nn in 0..nb {
if k == i && nn >= j {
break;
}
if n == (((EBANDS[nn + 1] - EBANDS[nn]) << k) >> 1) as usize {
index[i * nb + j] = index[k * nb + nn];
break 'search;
}
}
}
if index[i * nb + j] == -1 && n != 0 {
let mut k = 0;
while k < MAX_PSEUDO && fits_in32(n, get_pulses(k + 1)) {
k += 1;
}
index[i * nb + j] = curr as i16;
entries.push((n, k, curr));
curr += (k + 1) as usize;
}
}
}
let mut bits = vec![0u8; curr];
for &(n, k, off) in &entries {
let maxk = get_pulses(k) as usize;
let tmp = required_bits(n, maxk, BITRES);
for j in 1..=k {
bits[off + j as usize] = (tmp[get_pulses(j) as usize] - 1) as u8;
}
bits[off] = k as u8;
}
(index, bits)
}
fn required_bits(n: usize, maxk: usize, frac: u32) -> Vec<i32> {
let mut out = vec![0i32; maxk + 1];
if n == 1 {
for o in out.iter_mut().skip(1) {
*o = 1 << frac;
}
} else {
for (k, o) in out.iter_mut().enumerate().skip(1) {
*o = log2_frac(pvq_v(n, k) as u32, frac);
}
}
out
}
fn compute_caps(m: &Mode) -> Vec<u8> {
let nb = NB_EBANDS;
let mut caps = vec![0u8; (MAX_LM + 1) * 2 * nb];
for i in 0..=MAX_LM as i32 {
for c in 1..=2i32 {
for j in 0..nb {
let mut n0 = EBANDS[j + 1] - EBANDS[j];
let max_bits = if n0 << i == 1 {
c * (1 + MAX_FINE_BITS) << BITRES
} else {
let mut lm0 = 0;
if n0 > 2 {
n0 >>= 1;
lm0 -= 1;
} else if n0 <= 1 {
lm0 = i.min(1);
n0 <<= lm0;
}
let pcache = m.cache(lm0, j);
let mut mb = pcache[pcache[0] as usize] as i32 + 1;
let mut n = n0;
for k in 0..(i - lm0) {
mb <<= 1;
let offset = ((m.log_n[j] + ((lm0 + k) << BITRES)) >> 1) - QTHETA_OFFSET;
let num = 459 * ((2 * n - 1) * offset + mb);
let den = ((2 * n - 1) << 9) - 459;
let qb = ((num + (den >> 1)) / den).min(57);
mb += qb;
n <<= 1;
}
if c == 2 {
mb <<= 1;
let offset = ((m.log_n[j] + (i << BITRES)) >> 1) - if n == 2 { QTHETA_OFFSET_TWOPHASE } else { QTHETA_OFFSET };
let ndof = 2 * n - 1 - (n == 2) as i32;
let p = if n == 2 { 512 } else { 487 };
let num = p * (mb + ndof * offset);
let den = (ndof << 9) - p;
let qb = ((num + (den >> 1)) / den).min(if n == 2 { 64 } else { 61 });
mb += qb;
}
let ndof = c * n + if c == 2 && n > 2 { 1 } else { 0 };
let mut offset = ((m.log_n[j] + (i << BITRES)) >> 1) - FINE_OFFSET;
if n == 2 {
offset += (1 << BITRES) >> 2;
}
let num = mb + ndof * offset;
let den = (ndof - 1) << BITRES;
let qb = ((num + (den >> 1)) / den).min(MAX_FINE_BITS);
mb += c * qb << BITRES;
mb
};
let w = c * ((EBANDS[j + 1] - EBANDS[j]) << i);
let v = (4 * max_bits / w) - 64;
caps[((i * 2 + c - 1) as usize) * nb + j] = v.clamp(0, 255) as u8;
}
}
}
caps
}
/// Result of the allocation process.
pub struct Allocation {
pub coded_bands: usize,
@@ -263,125 +27,43 @@ pub struct Allocation {
pub fine_priority: [i32; NB_EBANDS],
}
/// `clt_compute_allocation`, encoder side. Stereo frames are always coded as dual (L/R) stereo
/// with no intensity bands, and no band is skipped voluntarily.
#[allow(clippy::too_many_arguments)]
pub fn compute_allocation(
m: &Mode,
start: usize,
end: usize,
offsets: &[i32; NB_EBANDS],
cap: &[i32; NB_EBANDS],
alloc_trim: i32,
total: i32,
c: usize,
lm: usize,
enc: &mut RangeEncoder,
) -> Allocation {
let ci = c as i32;
let lmi = lm as i32;
let mut total = total.max(0);
let mut skip_start = start;
let skip_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
total -= skip_rsv;
let mut intensity_rsv = 0;
let mut dual_stereo_rsv = 0;
if c == 2 {
intensity_rsv = LOG2_FRAC_TABLE[end - start];
if intensity_rsv > total {
intensity_rsv = 0;
} else {
total -= intensity_rsv;
dual_stereo_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
total -= dual_stereo_rsv;
}
}
let mut bits1 = [0i32; NB_EBANDS];
let mut bits2 = [0i32; NB_EBANDS];
let mut thresh = [0i32; NB_EBANDS];
let mut trim_offset = [0i32; NB_EBANDS];
for j in start..end {
let w = EBANDS[j + 1] - EBANDS[j];
thresh[j] = (ci << BITRES).max((3 * w << lmi << BITRES) >> 4);
trim_offset[j] = ci * w * (alloc_trim - 5 - lmi) * (end as i32 - j as i32 - 1) * (1 << (lmi + BITRES as i32)) >> 6;
if w << lmi == 1 {
trim_offset[j] -= ci << BITRES;
}
}
let nb_alloc = ALLOC.len() as i32;
let mut lo = 1;
let mut hi = nb_alloc - 1;
loop {
let mut done = false;
let mut psum = 0;
let mid = (lo + hi) >> 1;
for j in (start..end).rev() {
let n = EBANDS[j + 1] - EBANDS[j];
let mut bitsj = ci * n * (ALLOC[mid as usize][j] as i32) << lmi >> 2;
if bitsj > 0 {
bitsj = (bitsj + trim_offset[j]).max(0);
}
bitsj += offsets[j];
if bitsj >= thresh[j] || done {
done = true;
psum += bitsj.min(cap[j]);
} else if bitsj >= ci << BITRES {
psum += ci << BITRES;
}
}
if psum > total {
hi = mid - 1;
} else {
lo = mid + 1;
}
if lo > hi {
break;
}
}
hi = lo;
lo -= 1;
for j in start..end {
let n = EBANDS[j + 1] - EBANDS[j];
let mut bits1j = ci * n * (ALLOC[lo as usize][j] as i32) << lmi >> 2;
let mut bits2j = if hi >= nb_alloc { cap[j] } else { ci * n * (ALLOC[hi as usize][j] as i32) << lmi >> 2 };
if bits1j > 0 {
bits1j = (bits1j + trim_offset[j]).max(0);
}
if bits2j > 0 {
bits2j = (bits2j + trim_offset[j]).max(0);
}
if lo > 0 {
bits1j += offsets[j];
}
bits2j += offsets[j];
if offsets[j] > 0 {
skip_start = j;
}
bits2j = (bits2j - bits1j).max(0);
bits1[j] = bits1j;
bits2[j] = bits2j;
}
interp_bits2pulses(m, start, end, skip_start, &bits1, &bits2, &thresh, cap, total, skip_rsv, intensity_rsv, dual_stereo_rsv, c, lm, enc)
/// Per-band limits, boosts and available budget for the allocation search.
pub struct AllocationInput<'a> {
pub offsets: &'a [i32; NB_EBANDS],
pub cap: &'a [i32; NB_EBANDS],
pub trim: i32,
pub bits: i32,
}
#[allow(clippy::too_many_arguments)]
fn interp_bits2pulses(
m: &Mode,
start: usize,
end: usize,
/// `clt_compute_allocation`, encoder side. Stereo frames are always coded as dual (L/R) stereo
/// with no intensity bands, and no band is skipped voluntarily.
pub fn compute_allocation(m: &Mode, frame: CeltFrame, input: AllocationInput<'_>, enc: &mut RangeEncoder) -> Allocation {
let CeltFrame { start, end, channels: c, lm } = frame;
let AllocationInput { offsets, cap, trim: alloc_trim, bits: total } = input;
let crate::opus::rate_common::Bracket { skip_start, bits1, bits2, thresh, total, skip_rsv, intensity_rsv, dual_stereo_rsv } =
crate::opus::rate_common::bracket(start, end, offsets, cap, alloc_trim, total, c, lm);
let interpolation =
AllocationInterpolation { skip_start, bits1: &bits1, bits2: &bits2, thresh: &thresh, cap, total, skip_rsv, intensity_rsv, dual_stereo_rsv };
interp_bits2pulses(m, frame, interpolation, enc)
}
/// Bracketing allocation vectors and signalling reserves for the interpolation stage.
struct AllocationInterpolation<'a> {
skip_start: usize,
bits1: &[i32; NB_EBANDS],
bits2: &[i32; NB_EBANDS],
thresh: &[i32; NB_EBANDS],
cap: &[i32; NB_EBANDS],
mut total: i32,
bits1: &'a [i32; NB_EBANDS],
bits2: &'a [i32; NB_EBANDS],
thresh: &'a [i32; NB_EBANDS],
cap: &'a [i32; NB_EBANDS],
total: i32,
skip_rsv: i32,
mut intensity_rsv: i32,
mut dual_stereo_rsv: i32,
c: usize,
lm: usize,
enc: &mut RangeEncoder,
) -> Allocation {
intensity_rsv: i32,
dual_stereo_rsv: i32,
}
fn interp_bits2pulses(m: &Mode, frame: CeltFrame, interpolation: AllocationInterpolation<'_>, enc: &mut RangeEncoder) -> Allocation {
let CeltFrame { start, end, channels: c, lm } = frame;
let AllocationInterpolation { skip_start, bits1, bits2, thresh, cap, mut total, skip_rsv, mut intensity_rsv, mut dual_stereo_rsv } =
interpolation;
let ci = c as i32;
let alloc_floor = ci << BITRES;
let stereo = (c > 1) as i32;
@@ -393,7 +75,7 @@ fn interp_bits2pulses(
let mut psum = 0;
let mut done = false;
for j in (start..end).rev() {
let tmp = bits1[j] + (mid * bits2[j] >> ALLOC_STEPS);
let tmp = bits1[j] + ((mid * bits2[j]) >> ALLOC_STEPS);
if tmp >= thresh[j] || done {
done = true;
psum += tmp.min(cap[j]);
@@ -411,7 +93,7 @@ fn interp_bits2pulses(
let mut psum = 0;
let mut done = false;
for j in (start..end).rev() {
let mut tmp = bits1[j] + (lo * bits2[j] >> ALLOC_STEPS);
let mut tmp = bits1[j] + ((lo * bits2[j]) >> ALLOC_STEPS);
if tmp < thresh[j] && !done {
tmp = if tmp >= alloc_floor { alloc_floor } else { 0 };
} else {
@@ -500,9 +182,9 @@ fn interp_bits2pulses(
if n == 2 {
offset += (den << BITRES) >> 2;
}
if bits[j] + offset < den * 2 << BITRES {
if bits[j] + offset < (den * 2) << BITRES {
offset += nclogn >> 2;
} else if bits[j] + offset < den * 3 << BITRES {
} else if bits[j] + offset < (den * 3) << BITRES {
offset += nclogn >> 3;
}
let mut eb = (bits[j] + offset + (den << (BITRES - 1))).max(0);
@@ -513,7 +195,7 @@ fn interp_bits2pulses(
eb = eb.min(MAX_FINE_BITS);
ebits[j] = eb;
fine_priority[j] = (eb * (den << BITRES) >= bits[j] + offset) as i32;
bits[j] -= ci * eb << BITRES;
bits[j] -= (ci * eb) << BITRES;
} else {
excess = (bit - (ci << BITRES)).max(0);
bits[j] = bit - excess;
@@ -523,7 +205,7 @@ fn interp_bits2pulses(
if excess > 0 {
let extra_fine = (excess >> (stereo + BITRES as i32)).min(MAX_FINE_BITS - ebits[j]);
ebits[j] += extra_fine;
let extra_bits = extra_fine * ci << BITRES;
let extra_bits = (extra_fine * ci) << BITRES;
fine_priority[j] = (extra_bits >= excess - balance) as i32;
excess -= extra_bits;
}
+13 -1
View File
@@ -45,6 +45,8 @@ fn design(fc: f64, beta: f64, delay: usize) -> Vec<f32> {
h.iter().map(|&v| v as f32).collect()
}
use crate::opus::dot::dot8;
/// Decimates one channel of 48 kHz audio by 3, 4 or 6.
#[derive(Clone)]
pub struct Downsampler {
@@ -77,7 +79,7 @@ impl Downsampler {
let t = taps - 1 + self.factor * j;
let win = &self.buf[t + 1 - taps..=t];
// h is symmetric, so the window can be taken in forward order.
out.push(win.iter().zip(&self.h).map(|(a, b)| a * b).sum());
out.push(dot8(win, &self.h));
}
let n = self.buf.len();
self.buf.copy_within(n - (taps - 1).., 0);
@@ -97,6 +99,16 @@ mod tests {
(x.iter().map(|&v| (v as f64).powi(2)).sum::<f64>() / x.len() as f64).sqrt()
}
#[test]
fn dot8_matches_sequential_sum() {
for len in [0usize, 1, 7, 8, 9, 63, 167, 251] {
let a: Vec<f32> = (0..len).map(|i| ((i * 37 % 101) as f32 - 50.0) / 50.0).collect();
let b: Vec<f32> = (0..len).map(|i| ((i * 53 % 89) as f32 - 44.0) / 44.0).collect();
let exact: f64 = a.iter().zip(&b).map(|(&x, &y)| x as f64 * y as f64).sum();
assert!((dot8(&a, &b) as f64 - exact).abs() < 1e-4, "len {len}");
}
}
#[test]
fn passes_band_and_rejects_aliases() {
for &(fs, pass, stop) in &[(16_000u32, 6_000.0, 8_600.0), (12_000, 4_500.0, 6_500.0), (8_000, 3_000.0, 4_500.0)] {
+104 -8
View File
@@ -69,28 +69,55 @@ pub fn levinson(r: &[f64], order: usize) -> Vec<f64> {
}
/// Evaluates the symmetric polynomial `p` (length `d + 1`, `d` even) as the cosine series
/// `e^{jωd/2} P(e^{jω})`.
fn cos_series(p: &[f64], w: f64) -> f64 {
/// `e^{jωd/2} P(e^{jω})`, with `cos_m(m)` giving `cos(m ω)`.
#[inline]
fn cos_series_with(p: &[f64], cos_m: impl Fn(usize) -> f64) -> f64 {
let h = (p.len() - 1) / 2;
let mut s = p[h];
for k in 0..h {
s += 2.0 * p[k] * ((h - k) as f64 * w).cos();
s += 2.0 * p[k] * cos_m(h - k);
}
s
}
fn cos_series(p: &[f64], w: f64) -> f64 {
cos_series_with(p, |m| (m as f64 * w).cos())
}
/// Number of grid intervals the root search scans over `[0, π]`.
const GRID: usize = 1024;
/// Largest multiple of ω in the series (half the LPC order, at most 16 / 2).
const MAX_H: usize = 8;
/// Bisection steps per root: the bracket shrinks to 3e-9 rad, far below one Q15 NLSF step (9.6e-5 rad).
const BISECT_STEPS: usize = 20;
/// `cos(m · π g / GRID)` for every grid point `g` and `m` in `0..=MAX_H`, computed with the same
/// expression as [`cos_series`], so the table values are bit-identical to calling `cos` there.
fn grid_cos() -> &'static [[f64; MAX_H + 1]] {
static TABLE: std::sync::OnceLock<Vec<[f64; MAX_H + 1]>> = std::sync::OnceLock::new();
TABLE.get_or_init(|| {
(0..=GRID)
.map(|g| {
let w = std::f64::consts::PI * g as f64 / GRID as f64;
std::array::from_fn(|m| (m as f64 * w).cos())
})
.collect()
})
}
fn roots(p: &[f64], out: &mut Vec<f64>) {
const GRID: usize = 1024;
let grid = grid_cos();
let at_grid = |g: usize| cos_series_with(p, |m| grid[g][m]);
let mut w0 = 0.0;
let mut f0 = cos_series(p, w0);
let mut f0 = at_grid(0);
for g in 1..=GRID {
let w1 = std::f64::consts::PI * g as f64 / GRID as f64;
let f1 = cos_series(p, w1);
let f1 = at_grid(g);
if f0 == 0.0 {
out.push(w0);
} else if f0 * f1 < 0.0 {
let (mut lo, mut hi, mut flo) = (w0, w1, f0);
for _ in 0..40 {
for _ in 0..BISECT_STEPS {
let mid = 0.5 * (lo + hi);
let fm = cos_series(p, mid);
if fm * flo <= 0.0 {
@@ -111,6 +138,9 @@ fn roots(p: &[f64], out: &mut Vec<f64>) {
/// when the root search fails (unstable or degenerate filter).
pub fn a2nlsf(a: &[f64]) -> Option<Vec<f64>> {
let d = a.len();
if d > 2 * MAX_H {
return None;
}
let mut c = vec![0f64; d + 2];
c[0] = 1.0;
for k in 0..d {
@@ -199,9 +229,20 @@ pub fn pitch_search(x: &[f32], start: usize, len: usize, fs_khz: usize) -> Pitch
let score = full[(lag - min_lag) as usize];
// Contour: per-subframe lag offsets around the chosen lag.
let cb: &[[i32; 4]] = if fs_khz == 8 { &CB_NB_20 } else { &CB_WB_20 };
// The contour search revisits the same (subframe, lag) pairs for neighbouring base lags and
// codebook entries, so each correlation is computed once.
let span = (18 * fs - min_lag + 1) as usize;
let memo = std::cell::RefCell::new(vec![f64::NAN; 4 * span]);
let sub_score = |k: usize, l: i32| -> f64 {
let l = l.clamp(min_lag, 18 * fs);
ncorr(x, start + k * sub..start + (k + 1) * sub, l as usize)
let slot = k * span + (l - min_lag) as usize;
let cached = memo.borrow()[slot];
if !cached.is_nan() {
return cached;
}
let v = ncorr(x, start + k * sub..start + (k + 1) * sub, l as usize);
memo.borrow_mut()[slot] = v;
v
};
let mut best = (f64::MIN, lag, 0usize);
for l0 in (lag - 2).max(min_lag)..=(lag + 2).min(max_lag) {
@@ -319,4 +360,59 @@ mod tests {
}
}
}
/// The root search as it was before the grid table: `cos` called for every evaluation.
fn roots_reference(p: &[f64], out: &mut Vec<f64>) {
let mut w0 = 0.0;
let mut f0 = cos_series(p, w0);
for g in 1..=GRID {
let w1 = std::f64::consts::PI * g as f64 / GRID as f64;
let f1 = cos_series(p, w1);
if f0 == 0.0 {
out.push(w0);
} else if f0 * f1 < 0.0 {
let (mut lo, mut hi, mut flo) = (w0, w1, f0);
for _ in 0..BISECT_STEPS {
let mid = 0.5 * (lo + hi);
let fm = cos_series(p, mid);
if fm * flo <= 0.0 {
hi = mid;
} else {
lo = mid;
flo = fm;
}
}
out.push(0.5 * (lo + hi));
}
w0 = w1;
f0 = f1;
}
}
#[test]
fn grid_table_roots_are_bit_identical_to_direct_cos() {
let mut seed = 7u64;
let mut rnd = move || {
seed ^= seed << 13;
seed ^= seed >> 7;
seed ^= seed << 17;
(seed >> 11) as f64 / (1u64 << 53) as f64 * 2.0 - 1.0
};
let mut found = 0;
for len in [11usize, 17] {
for _ in 0..300 {
let mut p = vec![0f64; len];
for k in 0..len / 2 + 1 {
p[k] = rnd();
p[len - 1 - k] = p[k];
}
let (mut a, mut b) = (Vec::new(), Vec::new());
roots(&p, &mut a);
roots_reference(&p, &mut b);
assert_eq!(a.iter().map(|v| v.to_bits()).collect::<Vec<_>>(), b.iter().map(|v| v.to_bits()).collect::<Vec<_>>());
found += a.len();
}
}
assert!(found > 1000, "{found}");
}
}
+158 -10
View File
@@ -129,6 +129,48 @@ struct Coded {
pulses: Vec<i32>,
}
/// Noise-feedback history (decoded − input), most recent first, as a double-length ring: each
/// sample is stored at `pos` and `pos + MAX_LPC_ORDER`, so `buf[pos..pos + MAX_LPC_ORDER]` is
/// always the contiguous window and a push costs two stores instead of a shift.
struct NfRing {
buf: [f64; 2 * MAX_LPC_ORDER],
/// Index of the most recent sample, always below `MAX_LPC_ORDER`.
pos: usize,
}
impl NfRing {
fn new(hist: &[f64; MAX_LPC_ORDER]) -> Self {
let mut buf = [0.0; 2 * MAX_LPC_ORDER];
buf[..MAX_LPC_ORDER].copy_from_slice(hist);
buf[MAX_LPC_ORDER..].copy_from_slice(hist);
NfRing { buf, pos: 0 }
}
/// The history, most recent first.
fn window(&self) -> &[f64] {
self.buf.get(self.pos..self.pos + MAX_LPC_ORDER).unwrap_or(&[])
}
/// Makes `v` the most recent sample and drops the oldest.
fn push(&mut self, v: f64) {
self.pos = self.pos.checked_sub(1).unwrap_or(MAX_LPC_ORDER - 1);
for i in [self.pos, self.pos + MAX_LPC_ORDER] {
if let Some(slot) = self.buf.get_mut(i) {
*slot = v;
}
}
}
/// The history as a plain array, most recent first.
fn to_array(&self) -> [f64; MAX_LPC_ORDER] {
let mut out = [0.0; MAX_LPC_ORDER];
for (o, v) in out.iter_mut().zip(self.window()) {
*o = *v;
}
out
}
}
#[derive(Clone)]
struct Channel {
fs_khz: usize,
@@ -237,7 +279,7 @@ impl Channel {
let sub = self.sub;
let order = self.order;
let st = &mut self.dec;
let nf = &mut self.nf;
let mut ring = NfRing::new(&self.nf);
let off = if p.signal_type == 0 { offset + INACTIVE_OFFSET } else { offset };
let gamma = nf_gamma(off);
let mut nf_c = [0f64; MAX_LPC_ORDER];
@@ -355,7 +397,7 @@ impl Channel {
}
let lpc_q14 = lpc_pred.saturating_mul(16);
// Target excitation (Q14) for this sample.
let fb: f64 = (0..order).map(|j| nf_c[j] * nf[j]).sum();
let fb: f64 = nf_c.iter().zip(ring.window()).take(order).map(|(c, e)| c * e).sum();
let tgt = (x[n] as f64 + fb).clamp(-32768.0, 32767.0) * inv_g - lpc_q14 as f64 - ltp_q14 as f64;
let sgn = if seed_v < 0 { -1.0 } else { 1.0 };
let u = sgn * tgt;
@@ -394,11 +436,11 @@ impl Channel {
let v = res.saturating_add(lpc_q14);
s_lpc[MAX_LPC_ORDER + i] = v;
xq[n] = sat16(rshift_round(smulww(v, gain_q10), 8)) as i16;
nf.copy_within(0..MAX_LPC_ORDER - 1, 1);
nf[0] = xq[n] as f64 - x[n] as f64;
ring.push(xq[n] as f64 - x[n] as f64);
}
s_lpc.copy_within(sub..sub + MAX_LPC_ORDER, 0);
}
self.nf = ring.to_array();
st.s_lpc_q14.copy_from_slice(&s_lpc[..MAX_LPC_ORDER]);
st.out_buf[..l].copy_from_slice(&xq);
(Coded { gain_ix, gains_q16, seed, pulses }, xq)
@@ -485,6 +527,14 @@ struct Prep {
pred_q13: [i32; 2],
}
/// One rate-loop trial: the frame coded at gain offset `offset`.
struct Trial {
offset: f64,
bits: i32,
state: SilkEncoder,
coder: RangeEncoder,
}
/// SILK encoder for one mono or stereo (mid/side) stream.
#[derive(Clone)]
pub struct SilkEncoder {
@@ -635,11 +685,20 @@ impl SilkEncoder {
pub fn encode(&mut self, input: &[Vec<f32>], target_bits: f64, max_bits: i32, enc: &mut RangeEncoder) {
let prep = self.prepare(input);
let start_bits = enc.tell();
let trial = |s: &Self, o: f64| -> i32 {
let mut t = s.clone();
let mut e = enc.clone();
t.code(&prep, o, &mut e);
e.tell() - start_bits
// Every trial codes the frame into a clone of the encoder and the range coder. The result
// is kept per offset: the hard-limit check below hits the memo for the chosen offset, and
// the final step adopts that trial instead of coding the frame once more.
let mut trials: Vec<Trial> = Vec::new();
let mut trial = |s: &Self, o: f64| -> i32 {
if let Some(t) = trials.iter().find(|t| t.offset == o) {
return t.bits;
}
let mut state = s.clone();
let mut coder = enc.clone();
state.code(&prep, o, &mut coder);
let bits = coder.tell() - start_bits;
trials.push(Trial { offset: o, bits, state, coder });
bits
};
// Bisection on the gain offset: the smallest offset (finest quantisation) within budget.
let target = target_bits.min(max_bits as f64);
@@ -701,8 +760,20 @@ impl SilkEncoder {
while trial(self, o) > max_bits && o < 12.0 {
o += 1.0;
}
match trials.iter().position(|t| t.offset == o) {
Some(i) => {
let t = trials.swap_remove(i);
*self = t.state;
*enc = t.coder;
}
None => self.code(&prep, o, enc),
}
self.end_frame(&prep, o);
}
/// Advances the input history and the frame counter after frame `prep` was coded at `o`.
fn end_frame(&mut self, prep: &Prep, o: f64) {
self.last_offset = o;
self.code(&prep, o, enc);
for ch in 0..self.channels {
self.ch[ch].push_history(&prep.x[ch]);
}
@@ -712,3 +783,80 @@ impl SilkEncoder {
self.frame += 1;
}
}
#[cfg(test)]
mod tests {
use super::*;
/// Deterministic speech-like test input: two harmonics with a moving pitch, a syllable
/// envelope, noise and short silences, at the internal rate and 16-bit scale.
fn signal(len: usize, fs_khz: usize, seed: u32) -> Vec<f32> {
let mut s = seed;
let fs = (fs_khz * 1000) as f64;
(0..len)
.map(|i| {
s = s.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
let noise = (s >> 8) as f64 / (1u32 << 24) as f64 - 0.5;
let t = i as f64 / fs;
let f0 = 140.0 + 40.0 * (t * 1.3).sin();
let env = ((t * 4.0).sin().max(0.0)).powf(0.7);
let voiced = (std::f64::consts::TAU * f0 * t).sin() + 0.5 * (std::f64::consts::TAU * 2.0 * f0 * t).sin();
(8000.0 * env * voiced + 600.0 * noise) as f32
})
.collect()
}
#[test]
fn nf_ring_matches_a_shifted_history() {
let mut hist = [0f64; MAX_LPC_ORDER];
for (i, h) in hist.iter_mut().enumerate() {
*h = i as f64 * 0.5 - 3.0;
}
let mut ring = NfRing::new(&hist);
assert_eq!(ring.window(), &hist[..]);
for n in 0..100 {
let v = (n as f64 * 0.37).sin() * 100.0;
hist.copy_within(0..MAX_LPC_ORDER - 1, 1);
hist[0] = v;
ring.push(v);
assert_eq!(ring.window(), &hist[..], "after push {n}");
}
assert_eq!(ring.to_array(), hist);
}
/// The rate loop adopts the memoised trial for the chosen offset. A second encoder that codes
/// every frame afresh at that offset (what the loop did before the memo) must produce the
/// same bytes, frame after frame, so the adopted encoder and range-coder states are exact.
#[test]
fn adopting_the_memoised_trial_equals_coding_the_frame_again() {
for (fs_khz, channels, target_bits, max_bits) in
[(8, 1, 200.0, 1000), (12, 1, 320.0, 1000), (16, 1, 480.0, 1000), (16, 2, 640.0, 1000), (16, 1, 900.0, 400), (8, 2, 120.0, 160)]
{
let mut memo = SilkEncoder::new(fs_khz, channels);
let mut fresh = memo.clone();
let l = memo.frame_len();
let frames = 40;
let left = signal(l * frames, fs_khz, 7);
let right: Vec<f32> = signal(l * frames + 37, fs_khz, 11)[37..].iter().map(|v| v * 0.6).collect();
for f in 0..frames {
let mut input = vec![left[f * l..(f + 1) * l].to_vec()];
if channels == 2 {
input.push(right[f * l..(f + 1) * l].to_vec());
}
let mut enc = RangeEncoder::new();
memo.encode(&input, target_bits, max_bits, &mut enc);
let o = memo.last_offset;
let prep = fresh.prepare(&input);
let mut enc_fresh = RangeEncoder::new();
fresh.code(&prep, o, &mut enc_fresh);
fresh.end_frame(&prep, o);
assert_eq!(enc.tell(), enc_fresh.tell(), "{fs_khz} kHz {channels} ch frame {f}");
assert_eq!(enc.done(1275), enc_fresh.done(1275), "{fs_khz} kHz {channels} ch frame {f}");
for c in 0..channels {
assert_eq!(memo.ch[c].nf, fresh.ch[c].nf, "noise feedback, channel {c}, frame {f}");
assert_eq!(memo.ch[c].dec.s_lpc_q14, fresh.ch[c].dec.s_lpc_q14, "LPC state, channel {c}, frame {f}");
}
}
}
}
}
+130
View File
@@ -0,0 +1,130 @@
//! Shared CELT forward complex FFT.
#[derive(Clone, Copy, Default, Debug)]
pub struct Cpx {
pub re: f32,
pub im: f32,
}
impl Cpx {
#[inline]
pub(crate) fn mul(self, o: Cpx) -> Cpx {
Cpx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re }
}
#[inline]
pub(crate) fn add(self, o: Cpx) -> Cpx {
Cpx { re: self.re + o.re, im: self.im + o.im }
}
#[inline]
pub(crate) fn sub(self, o: Cpx) -> Cpx {
Cpx { re: self.re - o.re, im: self.im - o.im }
}
}
/// Mixed-radix (2, 3, 4, 5) forward complex FFT, unscaled (decimation in time, recursive).
pub struct Fft {
pub(crate) n: usize,
pub(crate) factors: Vec<usize>,
pub(crate) twiddle: Vec<Cpx>,
}
impl Fft {
pub fn new(n: usize) -> Fft {
let mut factors = Vec::new();
let mut m = n;
for p in [4usize, 2, 3, 5] {
while m.is_multiple_of(p) {
factors.push(p);
m /= p;
}
}
assert_eq!(m, 1, "unsupported FFT size {n}");
let twiddle = (0..n)
.map(|k| {
let ph = -2.0 * std::f64::consts::PI * k as f64 / n as f64;
Cpx { re: ph.cos() as f32, im: ph.sin() as f32 }
})
.collect();
Fft { n, factors, twiddle }
}
pub fn process(&self, data: &mut [Cpx], scratch: &mut Vec<Cpx>) {
scratch.clear();
scratch.extend_from_slice(&data[..self.n]);
self.rec(&mut data[..self.n], scratch, 1, self.n, 0, 1);
}
fn rec(&self, out: &mut [Cpx], inp: &[Cpx], in_stride: usize, n: usize, fi: usize, tw_stride: usize) {
let p = self.factors[fi];
let m = n / p;
if m == 1 {
for (i, o) in out.iter_mut().enumerate().take(p) {
*o = inp[i * in_stride];
}
} else {
for q in 0..p {
self.rec(&mut out[q * m..(q + 1) * m], &inp[q * in_stride..], in_stride * p, m, fi + 1, tw_stride * p);
}
}
// The twiddle index q * k * tw_stride is always below n, so no modulo is needed.
let tw = &self.twiddle;
match p {
2 => {
for k in 0..m {
let a0 = out[k];
let a1 = out[m + k].mul(tw[k * tw_stride]);
out[k] = a0.add(a1);
out[m + k] = a0.sub(a1);
}
}
4 => {
for k in 0..m {
let t0 = out[k];
let t1 = out[m + k].mul(tw[k * tw_stride]);
let t2 = out[2 * m + k].mul(tw[2 * k * tw_stride]);
let t3 = out[3 * m + k].mul(tw[3 * k * tw_stride]);
let (s0, d0) = (t0.add(t2), t0.sub(t2));
let (s1, d1) = (t1.add(t3), t1.sub(t3));
out[k] = s0.add(s1);
out[2 * m + k] = s0.sub(s1);
// The odd outputs combine d0 with -j * d1 = (d1.im, -d1.re) and its negative.
out[m + k] = Cpx { re: d0.re + d1.im, im: d0.im - d1.re };
out[3 * m + k] = Cpx { re: d0.re - d1.im, im: d0.im + d1.re };
}
}
3 => {
// Imaginary part of exp(-2 pi i / 3) = -sqrt(3) / 2.
let h = tw[self.n / 3].im;
for k in 0..m {
let t0 = out[k];
let t1 = out[m + k].mul(tw[k * tw_stride]);
let t2 = out[2 * m + k].mul(tw[2 * k * tw_stride]);
let (s, d) = (t1.add(t2), t1.sub(t2));
let a = Cpx { re: t0.re - 0.5 * s.re, im: t0.im - 0.5 * s.im };
out[k] = t0.add(s);
// j * h * d = (-h * d.im, h * d.re)
out[m + k] = Cpx { re: a.re - h * d.im, im: a.im + h * d.re };
out[2 * m + k] = Cpx { re: a.re + h * d.im, im: a.im - h * d.re };
}
}
_ => {
// Generic DFT butterfly (radix 5, once per transform).
let roots: [Cpx; 5] = std::array::from_fn(|q| if q < p { tw[q * (self.n / p)] } else { Cpx::default() });
let mut t = [Cpx::default(); 5];
for k in 0..m {
t[0] = out[k];
for q in 1..p {
t[q] = out[q * m + k].mul(tw[q * k * tw_stride]);
}
for q2 in 0..p {
let mut acc = t[0];
for q in 1..p {
acc = acc.add(t[q].mul(roots[(q * q2) % p]));
}
out[q2 * m + k] = acc;
}
}
}
}
}
}
+6 -2
View File
@@ -7,14 +7,18 @@
//! 20 ms, mono or stereo). From EffectCraft's `effectcraft-opusenc` (storytold/effectcraft@c618429).
//!
//! Public items keep their names, so FilmCraft and EffectCraft can re-export this module. The two
//! halves come from separate crates and do not share code yet (each has its own range coder, MDCT
//! and band tables). [`Bandwidth`] is one type for both (`encoder::Bandwidth` is the same type);
//! halves share the FFT, resampling dot product and CELT allocation preparation; range coders and
//! mode-specific MDCT processing remain separate. [`Bandwidth`] is one type for both (`encoder::Bandwidth` is the same type);
//! the two `Mode` enums keep their apps' variant names and convert into each other.
// Index loops and long argument lists follow the specification's pseudo-code (FilmCraft and
// EffectCraft allow these lints workspace-wide).
#![allow(clippy::needless_range_loop, clippy::too_many_arguments)]
mod dot;
mod fft;
mod rate_common;
#[cfg(feature = "opus-decode")]
mod decode;
#[cfg(feature = "opus-encode")]
+362
View File
@@ -0,0 +1,362 @@
//! CELT pulse cache and allocation caps shared by encoder and decoder.
#[cfg(not(feature = "opus-encode"))]
use super::decode::celt::tables::{ALLOC, EBANDS, LOG2_FRAC_TABLE, MAX_LM, NB_EBANDS};
#[cfg(feature = "opus-encode")]
use super::encoder::tables::{ALLOC, EBANDS, LOG2_FRAC_TABLE, MAX_LM, NB_EBANDS};
const BITRES: u32 = 3;
const MAX_PSEUDO: i32 = 40;
const LOG_MAX_PSEUDO: i32 = 6;
const MAX_FINE_BITS: i32 = 8;
const FINE_OFFSET: i32 = 21;
const QTHETA_OFFSET: i32 = 4;
const QTHETA_OFFSET_TWOPHASE: i32 = 16;
fn ilog(x: u32) -> i32 {
(32 - x.leading_zeros()) as i32
}
/// Number of pulses represented by pseudo-pulse index `i`.
pub fn get_pulses(i: i32) -> i32 {
if i < 8 { i } else { (8 + (i & 7)) << ((i >> 3) - 1) }
}
/// Conservative (rounded up) log2 of `val` with `frac` fractional bits.
pub fn log2_frac(mut val: u32, mut frac: u32) -> i32 {
let mut l = ilog(val);
if val & val.wrapping_sub(1) != 0 {
if l > 16 {
val = ((val - 1) >> (l - 16)) + 1;
} else {
val <<= 16 - l;
}
let mut l = (l - 1) << frac;
loop {
let b = (val >> 16) as i32;
l += b << frac;
val = (val + b as u32) >> b;
val = (val * val + 0x7FFF) >> 15;
if frac == 0 {
break;
}
frac -= 1;
}
l + (val > 0x8000) as i32
} else {
l -= 1;
l << frac
}
}
/// PVQ codebook size V(N, K) (saturating far above 2^32).
pub fn pvq_v(n: usize, k: usize) -> u128 {
if k == 0 {
return 1;
}
if n == 0 {
return 0;
}
let mut row = vec![0u128; k + 1];
row[0] = 1;
for _ in 0..n {
let mut prev_diag = row[0];
for kk in 1..=k {
let up = row[kk];
let v = up.saturating_add(row[kk - 1]).saturating_add(prev_diag);
prev_diag = up;
row[kk] = v.min(u128::MAX >> 8);
}
row[0] = 1;
}
row[k]
}
fn fits_in32(n: usize, k: i32) -> bool {
pvq_v(n, k as usize) <= u32::MAX as u128
}
/// Precomputed per-mode data.
pub struct Mode {
/// log2 of band width in 1/8 bits.
pub log_n: [i32; NB_EBANDS],
pub(crate) cache_index: Vec<i16>,
pub(crate) cache_bits: Vec<u8>,
pub(crate) caps: Vec<u8>,
}
impl Mode {
pub fn new() -> Mode {
let mut log_n = [0i32; NB_EBANDS];
for (i, l) in log_n.iter_mut().enumerate() {
*l = log2_frac((EBANDS[i + 1] - EBANDS[i]) as u32, BITRES);
}
let (cache_index, cache_bits) = compute_pulse_cache(MAX_LM as i32);
let mut m = Mode { log_n, cache_index, cache_bits, caps: Vec::new() };
m.caps = compute_caps(&m);
m
}
#[inline]
pub fn cache(&self, lm: i32, band: usize) -> &[u8] {
let idx = self.cache_index[((lm + 1) as usize) * NB_EBANDS + band];
&self.cache_bits[idx.max(0) as usize..]
}
pub fn bits2pulses(&self, band: usize, lm: i32, bits: i32) -> i32 {
let cache = self.cache(lm, band);
let mut lo = 0i32;
let mut hi = cache[0] as i32;
let bits = bits - 1;
for _ in 0..LOG_MAX_PSEUDO {
let mid = (lo + hi + 1) >> 1;
if cache[mid as usize] as i32 >= bits {
hi = mid;
} else {
lo = mid;
}
}
let lo_bits = if lo == 0 { -1 } else { cache[lo as usize] as i32 };
if bits - lo_bits <= cache[hi as usize] as i32 - bits { lo } else { hi }
}
pub fn pulses2bits(&self, band: usize, lm: i32, pulses: i32) -> i32 {
if pulses == 0 { 0 } else { self.cache(lm, band)[pulses as usize] as i32 + 1 }
}
/// Per-band allocation caps for this frame (`init_caps`).
pub fn init_caps(&self, lm: usize, c: usize) -> [i32; NB_EBANDS] {
let mut cap = [0i32; NB_EBANDS];
for (i, cp) in cap.iter_mut().enumerate() {
let n = (EBANDS[i + 1] - EBANDS[i]) << lm;
*cp = ((self.caps[NB_EBANDS * (2 * lm + c - 1) + i] as i32 + 64) * c as i32 * n) >> 2;
}
cap
}
}
fn compute_pulse_cache(lm_max: i32) -> (Vec<i16>, Vec<u8>) {
let nb = NB_EBANDS;
let rows = (lm_max + 2) as usize;
let mut index = vec![-1i16; nb * rows];
let mut entries: Vec<(usize, i32, usize)> = Vec::new();
let mut curr = 0usize;
for i in 0..rows {
for j in 0..nb {
let n = (((EBANDS[j + 1] - EBANDS[j]) << i) >> 1) as usize;
index[i * nb + j] = -1;
'search: for k in 0..=i {
for nn in 0..nb {
if k == i && nn >= j {
break;
}
if n == (((EBANDS[nn + 1] - EBANDS[nn]) << k) >> 1) as usize {
index[i * nb + j] = index[k * nb + nn];
break 'search;
}
}
}
if index[i * nb + j] == -1 && n != 0 {
let mut k = 0;
while k < MAX_PSEUDO && fits_in32(n, get_pulses(k + 1)) {
k += 1;
}
index[i * nb + j] = curr as i16;
entries.push((n, k, curr));
curr += (k + 1) as usize;
}
}
}
let mut bits = vec![0u8; curr];
for &(n, k, off) in &entries {
let maxk = get_pulses(k) as usize;
let tmp = required_bits(n, maxk, BITRES);
for j in 1..=k {
bits[off + j as usize] = (tmp[get_pulses(j) as usize] - 1) as u8;
}
bits[off] = k as u8;
}
(index, bits)
}
fn required_bits(n: usize, maxk: usize, frac: u32) -> Vec<i32> {
let mut out = vec![0i32; maxk + 1];
if n == 1 {
for o in out.iter_mut().skip(1) {
*o = 1 << frac;
}
} else {
for (k, o) in out.iter_mut().enumerate().skip(1) {
*o = log2_frac(pvq_v(n, k) as u32, frac);
}
}
out
}
fn compute_caps(m: &Mode) -> Vec<u8> {
let nb = NB_EBANDS;
let mut caps = vec![0u8; (MAX_LM + 1) * 2 * nb];
for i in 0..=MAX_LM as i32 {
for c in 1..=2i32 {
for j in 0..nb {
let mut n0 = EBANDS[j + 1] - EBANDS[j];
let max_bits = if n0 << i == 1 {
(c * (1 + MAX_FINE_BITS)) << BITRES
} else {
let mut lm0 = 0;
if n0 > 2 {
n0 >>= 1;
lm0 -= 1;
} else if n0 <= 1 {
lm0 = i.min(1);
n0 <<= lm0;
}
let pcache = m.cache(lm0, j);
let mut mb = pcache[pcache[0] as usize] as i32 + 1;
let mut n = n0;
for k in 0..(i - lm0) {
mb <<= 1;
let offset = ((m.log_n[j] + ((lm0 + k) << BITRES)) >> 1) - QTHETA_OFFSET;
let num = 459 * ((2 * n - 1) * offset + mb);
let den = ((2 * n - 1) << 9) - 459;
let qb = ((num + (den >> 1)) / den).min(57);
mb += qb;
n <<= 1;
}
if c == 2 {
mb <<= 1;
let offset = ((m.log_n[j] + (i << BITRES)) >> 1) - if n == 2 { QTHETA_OFFSET_TWOPHASE } else { QTHETA_OFFSET };
let ndof = 2 * n - 1 - (n == 2) as i32;
let p = if n == 2 { 512 } else { 487 };
let num = p * (mb + ndof * offset);
let den = (ndof << 9) - p;
let qb = ((num + (den >> 1)) / den).min(if n == 2 { 64 } else { 61 });
mb += qb;
}
let ndof = c * n + if c == 2 && n > 2 { 1 } else { 0 };
let mut offset = ((m.log_n[j] + (i << BITRES)) >> 1) - FINE_OFFSET;
if n == 2 {
offset += (1 << BITRES) >> 2;
}
let num = mb + ndof * offset;
let den = (ndof - 1) << BITRES;
let qb = ((num + (den >> 1)) / den).min(MAX_FINE_BITS);
mb += (c * qb) << BITRES;
mb
};
let w = c * ((EBANDS[j + 1] - EBANDS[j]) << i);
let v = (4 * max_bits / w) - 64;
caps[((i * 2 + c - 1) as usize) * nb + j] = v.clamp(0, 255) as u8;
}
}
}
caps
}
/// Shared allocation search before encoder/decoder signalling diverges.
pub struct Bracket {
pub skip_start: usize,
pub bits1: [i32; NB_EBANDS],
pub bits2: [i32; NB_EBANDS],
pub thresh: [i32; NB_EBANDS],
pub total: i32,
pub skip_rsv: i32,
pub intensity_rsv: i32,
pub dual_stereo_rsv: i32,
}
pub fn bracket(
start: usize,
end: usize,
offsets: &[i32; NB_EBANDS],
cap: &[i32; NB_EBANDS],
alloc_trim: i32,
total: i32,
c: usize,
lm: usize,
) -> Bracket {
let ci = c as i32;
let lmi = lm as i32;
let mut total = total.max(0);
let mut skip_start = start;
let skip_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
total -= skip_rsv;
let mut intensity_rsv = 0;
let mut dual_stereo_rsv = 0;
if c == 2 {
intensity_rsv = LOG2_FRAC_TABLE[end - start];
if intensity_rsv > total {
intensity_rsv = 0;
} else {
total -= intensity_rsv;
dual_stereo_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
total -= dual_stereo_rsv;
}
}
let mut bits1 = [0i32; NB_EBANDS];
let mut bits2 = [0i32; NB_EBANDS];
let mut thresh = [0i32; NB_EBANDS];
let mut trim_offset = [0i32; NB_EBANDS];
for j in start..end {
let w = EBANDS[j + 1] - EBANDS[j];
thresh[j] = (ci << BITRES).max(((3 * w) << lmi << BITRES) >> 4);
trim_offset[j] = (ci * w * (alloc_trim - 5 - lmi) * (end as i32 - j as i32 - 1) * (1 << (lmi + BITRES as i32))) >> 6;
if w << lmi == 1 {
trim_offset[j] -= ci << BITRES;
}
}
let nb_alloc = ALLOC.len() as i32;
let mut lo = 1;
let mut hi = nb_alloc - 1;
loop {
let mut done = false;
let mut psum = 0;
let mid = (lo + hi) >> 1;
for j in (start..end).rev() {
let n = EBANDS[j + 1] - EBANDS[j];
let mut bitsj = (ci * n * (ALLOC[mid as usize][j] as i32)) << lmi >> 2;
if bitsj > 0 {
bitsj = (bitsj + trim_offset[j]).max(0);
}
bitsj += offsets[j];
if bitsj >= thresh[j] || done {
done = true;
psum += bitsj.min(cap[j]);
} else if bitsj >= ci << BITRES {
psum += ci << BITRES;
}
}
if psum > total {
hi = mid - 1;
} else {
lo = mid + 1;
}
if lo > hi {
break;
}
}
hi = lo;
lo -= 1;
for j in start..end {
let n = EBANDS[j + 1] - EBANDS[j];
let mut bits1j = (ci * n * (ALLOC[lo as usize][j] as i32)) << lmi >> 2;
let mut bits2j = if hi >= nb_alloc { cap[j] } else { (ci * n * (ALLOC[hi as usize][j] as i32)) << lmi >> 2 };
if bits1j > 0 {
bits1j = (bits1j + trim_offset[j]).max(0);
}
if bits2j > 0 {
bits2j = (bits2j + trim_offset[j]).max(0);
}
if lo > 0 {
bits1j += offsets[j];
}
bits2j += offsets[j];
if offsets[j] > 0 {
skip_start = j;
}
bits2j = (bits2j - bits1j).max(0);
bits1[j] = bits1j;
bits2[j] = bits2j;
}
Bracket { skip_start, bits1, bits2, thresh, total, skip_rsv, intensity_rsv, dual_stereo_rsv }
}
+411
View File
@@ -0,0 +1,411 @@
//! QOA ("Quite OK Audio"): a decoder (feature `qoa-decode`) and an encoder (feature `qoa-encode`)
//! for whole `.qoa` files, 16-bit, 1 to 8 channels.
//!
//! Written from the published QOA specification (qoaformat.org). A file is an 8-byte header (the
//! magic `qoaf` and the number of samples per channel) followed by frames of up to 5120 samples
//! per channel. Each frame starts with its channel count, sample rate, sample count and size, then
//! the state of one 4-tap sign-sign LMS predictor per channel, then 64-bit slices of 20 samples:
//! a 4-bit scale factor and twenty 3-bit quantised residuals, the channels interleaved slice by
//! slice.
//!
//! Streaming files (a sample count of 0 in the header) are not supported.
//! Samples are `i16`, one `Vec` per channel.
#[cfg(feature = "qoa-decode")]
const MAX_FRAME_SAMPLES: usize = 5120;
const SLICE_SAMPLES: usize = 20;
const LMS_LEN: usize = 4;
const MAGIC: &[u8; 4] = b"qoaf";
/// The most channels a file may have.
pub const MAX_CHANNELS: usize = 8;
/// `dequant[scale factor][quantised residual]`: `round(round((sf + 1)^2.75) * [0.75, -0.75, 2.5,
/// -2.5, 4.5, -4.5, 7, -7])`.
const DEQUANT: [[i32; 8]; 16] = [
[1, -1, 3, -3, 5, -5, 7, -7],
[5, -5, 18, -18, 32, -32, 49, -49],
[16, -16, 53, -53, 95, -95, 147, -147],
[34, -34, 113, -113, 203, -203, 315, -315],
[63, -63, 210, -210, 378, -378, 588, -588],
[104, -104, 345, -345, 621, -621, 966, -966],
[158, -158, 528, -528, 950, -950, 1477, -1477],
[228, -228, 760, -760, 1368, -1368, 2128, -2128],
[316, -316, 1053, -1053, 1895, -1895, 2947, -2947],
[422, -422, 1405, -1405, 2529, -2529, 3934, -3934],
[548, -548, 1828, -1828, 3290, -3290, 5117, -5117],
[696, -696, 2320, -2320, 4176, -4176, 6496, -6496],
[868, -868, 2893, -2893, 5207, -5207, 8099, -8099],
[1064, -1064, 3548, -3548, 6386, -6386, 9933, -9933],
[1286, -1286, 4288, -4288, 7718, -7718, 12005, -12005],
[1536, -1536, 5120, -5120, 9216, -9216, 14336, -14336],
];
/// What went wrong reading or writing a QOA file.
#[non_exhaustive]
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum Error {
/// The input is not a QOA file, or is damaged or truncated.
#[error("malformed QOA: {0}")]
Malformed(&'static str),
/// A valid file this module does not handle (a streaming file).
#[error("unsupported QOA: {0}")]
Unsupported(&'static str),
/// The samples or settings given to the encoder cannot be written as QOA.
#[error("QOA cannot encode: {0}")]
InvalidInput(&'static str),
}
/// A decoded file.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Audio {
/// Sample rate in Hz (1 to 16 777 215).
pub sample_rate: u32,
/// One `Vec` of samples per channel, all the same length.
pub channels: Vec<Vec<i16>>,
}
/// The predictor: the last four samples and four weights.
#[derive(Clone, Copy)]
struct Lms {
history: [i32; LMS_LEN],
weights: [i32; LMS_LEN],
}
impl Lms {
fn new() -> Self {
Lms { history: [0; LMS_LEN], weights: [0, 0, -(1 << 13), 1 << 14] }
}
fn predict(&self) -> i32 {
let mut p = 0i32;
for i in 0..LMS_LEN {
p = p.wrapping_add(self.weights[i].wrapping_mul(self.history[i]));
}
p >> 13
}
fn update(&mut self, sample: i32, residual: i32) {
let delta = residual >> 4;
for i in 0..LMS_LEN {
self.weights[i] += if self.history[i] < 0 { -delta } else { delta };
}
self.history.copy_within(1.., 0);
self.history[LMS_LEN - 1] = sample;
}
}
fn clamp16(v: i32) -> i32 {
v.clamp(-32768, 32767)
}
#[cfg(feature = "qoa-decode")]
mod decode {
use super::{Audio, DEQUANT, Error, LMS_LEN, Lms, MAGIC, MAX_CHANNELS, MAX_FRAME_SAMPLES, SLICE_SAMPLES, clamp16};
fn be16(b: &[u8], i: usize) -> u16 {
u16::from_be_bytes([b[i], b[i + 1]])
}
/// Decode a whole `.qoa` file.
///
/// The declared length is checked against the input before anything is allocated: a slice of
/// 8 bytes holds at most 20 samples, so a file cannot declare more samples than that.
pub fn decode(bytes: &[u8]) -> Result<Audio, Error> {
if bytes.len() < 8 || &bytes[..4] != MAGIC {
return Err(Error::Malformed("missing the qoaf magic"));
}
let total = u32::from_be_bytes([bytes[4], bytes[5], bytes[6], bytes[7]]) as usize;
if total == 0 {
return Err(Error::Unsupported("streaming files (a sample count of 0)"));
}
if bytes.len() < 16 {
return Err(Error::Malformed("truncated frame header"));
}
let channels = usize::from(bytes[8]);
let sample_rate = u32::from_be_bytes([0, bytes[9], bytes[10], bytes[11]]);
if channels == 0 || channels > MAX_CHANNELS || sample_rate == 0 {
return Err(Error::Malformed("bad channel count or sample rate"));
}
// 8 bytes (20 samples) per channel at the very least, plus the frame headers.
let room = (bytes.len() - 8) / (8 * channels) * SLICE_SAMPLES;
if total > room {
return Err(Error::Malformed("the file is too short for its declared length"));
}
let mut out: Vec<Vec<i16>> = Vec::new();
for _ in 0..channels {
let mut v = Vec::new();
v.try_reserve_exact(total).map_err(|_| Error::Malformed("too many samples"))?;
out.push(v);
}
let mut pos = 8;
let mut done = 0usize;
while done < total {
let head = bytes.get(pos..pos + 8).ok_or(Error::Malformed("truncated frame header"))?;
let rate = u32::from_be_bytes([0, head[1], head[2], head[3]]);
if usize::from(head[0]) != channels || rate != sample_rate {
return Err(Error::Malformed("the channel count or sample rate changes between frames"));
}
let samples = usize::from(be16(head, 4));
let size = usize::from(be16(head, 6));
let slices = samples.div_ceil(SLICE_SAMPLES);
if samples == 0 || samples > MAX_FRAME_SAMPLES || samples > total - done {
return Err(Error::Malformed("bad frame sample count"));
}
if size != 8 + 16 * channels + 8 * slices * channels {
return Err(Error::Malformed("frame size does not match its sample count"));
}
let frame = bytes.get(pos..pos + size).ok_or(Error::Malformed("truncated frame"))?;
let mut lms = [Lms::new(); MAX_CHANNELS];
for (c, state) in lms.iter_mut().take(channels).enumerate() {
let at = 8 + c * 16;
for i in 0..LMS_LEN {
state.history[i] = i32::from(be16(frame, at + 2 * i) as i16);
state.weights[i] = i32::from(be16(frame, at + 8 + 2 * i) as i16);
}
}
let mut at = 8 + 16 * channels;
for s in 0..slices {
let n = (samples - s * SLICE_SAMPLES).min(SLICE_SAMPLES);
for (c, state) in lms.iter_mut().take(channels).enumerate() {
let mut slice = u64::from_be_bytes([
frame[at],
frame[at + 1],
frame[at + 2],
frame[at + 3],
frame[at + 4],
frame[at + 5],
frame[at + 6],
frame[at + 7],
]);
at += 8;
let table = &DEQUANT[(slice >> 60) as usize & 15];
for _ in 0..n {
let dequantised = table[(slice >> 57) as usize & 7];
slice <<= 3;
let sample = clamp16(state.predict() + dequantised);
out[c].push(sample as i16);
state.update(sample, dequantised);
}
}
}
pos += size;
done += samples;
}
Ok(Audio { sample_rate, channels: out })
}
}
#[cfg(feature = "qoa-decode")]
pub use decode::decode;
#[cfg(feature = "qoa-encode")]
mod encode {
use super::{DEQUANT, Error, Lms, MAGIC, MAX_CHANNELS, SLICE_SAMPLES, clamp16};
/// The quantised residual (0..8) whose dequantised value is nearest `residual`.
fn quantise(table: &[i32; 8], residual: i32) -> usize {
let mut best = 0;
let mut best_err = i64::MAX;
for (q, &d) in table.iter().enumerate() {
let e = i64::from(residual - d).pow(2);
if e < best_err {
best = q;
best_err = e;
}
}
best
}
/// Encode one slice of one channel with every scale factor and keep the one with the least
/// squared error. Returns the 64-bit slice; `lms` is advanced to the chosen result.
fn encode_slice(lms: &mut Lms, samples: &[i16]) -> u64 {
let mut best: Option<(i64, u64, Lms)> = None;
for (sf, table) in DEQUANT.iter().enumerate() {
let mut trial = *lms;
let mut slice = sf as u64;
let mut err = 0i64;
for k in 0..SLICE_SAMPLES {
let mut q = 0;
if let Some(&s) = samples.get(k) {
let predicted = trial.predict();
q = quantise(table, i32::from(s) - predicted);
let sample = clamp16(predicted + table[q]);
err += i64::from(i32::from(s) - sample).pow(2);
trial.update(sample, table[q]);
}
slice = slice << 3 | q as u64;
}
// 4 + 60 bits are in `slice`; the scale factor belongs on top.
let slice = slice & ((1 << 60) - 1) | (sf as u64) << 60;
if best.as_ref().is_none_or(|b| err < b.0) {
best = Some((err, slice, trial));
}
}
match best {
Some((_, slice, state)) => {
*lms = state;
slice
}
None => 0,
}
}
/// Encode `channels` (one `Vec` of samples per channel, all the same length) as a `.qoa` file.
pub fn encode(sample_rate: u32, channels: &[Vec<i16>]) -> Result<Vec<u8>, Error> {
let n = channels.len();
if n == 0 || n > MAX_CHANNELS {
return Err(Error::InvalidInput("QOA stores 1 to 8 channels"));
}
if sample_rate == 0 || sample_rate > 0x00ff_ffff {
return Err(Error::InvalidInput("the sample rate must be 1 to 16777215 Hz"));
}
let total = channels[0].len();
if channels.iter().any(|c| c.len() != total) {
return Err(Error::InvalidInput("the channels differ in length"));
}
let total32 = u32::try_from(total).map_err(|_| Error::InvalidInput("too many samples"))?;
if total == 0 {
return Err(Error::InvalidInput("QOA cannot store an empty file"));
}
let mut out = Vec::with_capacity(8 + total * n / 2);
out.extend_from_slice(MAGIC);
out.extend_from_slice(&total32.to_be_bytes());
let mut lms = [Lms::new(); MAX_CHANNELS];
let mut start = 0;
while start < total {
let len = (total - start).min(5120);
let slices = len.div_ceil(SLICE_SAMPLES);
let size = 8 + 16 * n + 8 * slices * n;
out.push(n as u8);
out.extend_from_slice(&sample_rate.to_be_bytes()[1..]);
out.extend_from_slice(&(len as u16).to_be_bytes());
out.extend_from_slice(&(size as u16).to_be_bytes());
// The state a frame starts from is written as 16-bit values, so the predictor
// continues from exactly what a decoder reads.
for state in lms.iter_mut().take(n) {
for v in state.history.iter_mut().chain(state.weights.iter_mut()) {
*v = i32::from(*v as i16);
out.extend_from_slice(&(*v as i16).to_be_bytes());
}
}
for s in 0..slices {
let from = start + s * SLICE_SAMPLES;
let to = (from + SLICE_SAMPLES).min(start + len);
for (c, state) in lms.iter_mut().take(n).enumerate() {
out.extend_from_slice(&encode_slice(state, &channels[c][from..to]).to_be_bytes());
}
}
start += len;
}
Ok(out)
}
}
#[cfg(feature = "qoa-encode")]
pub use encode::encode;
#[cfg(all(test, feature = "qoa-decode", feature = "qoa-encode"))]
mod tests {
use super::*;
fn tone(frames: usize, ch: usize) -> Vec<Vec<i16>> {
(0..ch)
.map(|c| (0..frames).map(|i| (((i as f64) * (0.03 + 0.01 * c as f64)).sin() * 12000.0 + ((i * 7919) % 200) as f64) as i16).collect())
.collect()
}
fn snr(a: &[i16], b: &[i16]) -> f64 {
let (mut s, mut e) = (0f64, 0f64);
for (&x, &y) in a.iter().zip(b) {
s += f64::from(x).powi(2);
e += (f64::from(x) - f64::from(y)).powi(2);
}
10.0 * (s / e.max(1.0)).log10()
}
#[test]
fn dequant_table_matches_its_formula() {
for (sf, row) in DEQUANT.iter().enumerate() {
let scale = ((sf as f64 + 1.0).powf(2.75)).round();
for (q, base) in [0.75, -0.75, 2.5, -2.5, 4.5, -4.5, 7.0, -7.0].into_iter().enumerate() {
assert_eq!(f64::from(row[q]), (scale * base).round(), "sf {sf} q {q}");
}
}
}
#[test]
fn round_trips_with_a_good_signal_to_noise_ratio() {
for (frames, ch) in [(1, 1), (19, 2), (20, 1), (21, 2), (5120, 1), (5121, 2), (12_345, 8)] {
let src = tone(frames, ch);
let bytes = encode(44_100, &src).unwrap();
let back = decode(&bytes).unwrap();
assert_eq!((back.sample_rate, back.channels.len(), back.channels[0].len()), (44_100, ch, frames));
if frames > 1000 {
for (c, (a, b)) in src.iter().zip(&back.channels).enumerate() {
assert!(snr(a, b) > 25.0, "{frames}x{ch} channel {c}");
}
}
}
}
#[test]
fn silence_and_full_scale_extremes_survive() {
let silent = vec![vec![0i16; 3000]];
// No residual value is zero, so silence decodes to a tiny residue, never exactly 0.
let quiet = decode(&encode(8000, &silent).unwrap()).unwrap();
assert!(quiet.channels[0].iter().all(|&s| s.abs() <= 2), "silence stays within 2 LSB");
let square: Vec<i16> = (0..4000).map(|i| if (i / 50) % 2 == 0 { i16::MAX } else { i16::MIN }).collect();
let back = decode(&encode(48_000, std::slice::from_ref(&square)).unwrap()).unwrap();
assert_eq!(back.channels[0].len(), square.len());
}
#[test]
fn the_file_has_the_documented_layout() {
let bytes = encode(48_000, &tone(100, 2)).unwrap();
assert_eq!(&bytes[..4], b"qoaf");
assert_eq!(u32::from_be_bytes(bytes[4..8].try_into().unwrap()), 100);
assert_eq!(bytes[8], 2);
assert_eq!(&bytes[9..12], &48_000u32.to_be_bytes()[1..]);
assert_eq!(u16::from_be_bytes([bytes[12], bytes[13]]), 100);
// 8 header + 2 channels * 16 state + 5 slices * 2 channels * 8
assert_eq!(usize::from(u16::from_be_bytes([bytes[14], bytes[15]])), 8 + 32 + 80);
assert_eq!(bytes.len(), 8 + 8 + 32 + 80);
// The first frame starts from the specified predictor state.
assert_eq!(&bytes[16 + 8..16 + 16], &[0, 0, 0, 0, 0xe0, 0, 0x40, 0]);
}
#[test]
fn invalid_input_to_the_encoder_is_refused() {
assert!(encode(44_100, &[]).is_err());
assert!(encode(0, &[vec![0; 10]]).is_err());
assert!(encode(1 << 24, &[vec![0; 10]]).is_err());
assert!(encode(44_100, &[vec![0; 10], vec![0; 9]]).is_err());
assert!(encode(44_100, &[vec![]]).is_err());
assert!(encode(44_100, &vec![vec![0; 10]; 9]).is_err());
}
#[test]
fn hostile_input_is_an_error_not_a_panic() {
let good = encode(44_100, &tone(6000, 2)).unwrap();
for len in 0..good.len().min(600) {
let _ = decode(&good[..len]);
}
assert!(decode(&good[..good.len() - 1]).is_err());
// A header that declares more samples than the bytes can hold.
let mut huge = good.clone();
huge[4..8].copy_from_slice(&u32::MAX.to_be_bytes());
assert!(decode(&huge).is_err());
// A streaming file, and a frame whose size field lies.
let mut streaming = good.clone();
streaming[4..8].fill(0);
assert_eq!(decode(&streaming), Err(Error::Unsupported("streaming files (a sample count of 0)")));
let mut lying = good.clone();
lying[14] ^= 1;
assert!(decode(&lying).is_err());
let mut zero_rate = good.clone();
zero_rate[9..12].fill(0);
assert!(decode(&zero_rate).is_err());
let mut changed = good;
let second = 8 + usize::from(u16::from_be_bytes([changed[14], changed[15]]));
changed[second] = 1;
assert!(decode(&changed).is_err());
}
}
+287
View File
@@ -0,0 +1,287 @@
//! Bit packing (Vorbis I §2) and codebooks (§3): Huffman lengths, the codeword assignment the
//! decoder derives from them, VQ lattices (lookup type 1) and the header encoding.
use super::{Error, Result};
/// LSB-first bit packer (Vorbis I §2.1.4): bits fill each byte from its least significant end.
#[derive(Clone, Debug, Default)]
pub struct BitWriter {
buf: Vec<u8>,
bits: u64,
}
impl BitWriter {
pub fn new() -> BitWriter {
BitWriter::default()
}
/// Writes the low `n` bits of `v` (`n` ≤ 32).
pub fn write(&mut self, v: u32, n: u32) {
let n = n.min(32);
for i in 0..n {
let bit = (v >> i) & 1;
let at = (self.bits / 8) as usize;
if at == self.buf.len() {
self.buf.push(0);
}
if bit != 0
&& let Some(b) = self.buf.get_mut(at)
{
*b |= 1 << (self.bits % 8);
}
self.bits += 1;
}
}
pub fn flag(&mut self, b: bool) {
self.write(b as u32, 1);
}
/// Writes a codeword MSB first: the decoder walks the tree from its first bit.
fn codeword(&mut self, word: u32, len: u32) {
for i in (0..len).rev() {
self.write((word >> i) & 1, 1);
}
}
pub fn bytes(&mut self, data: &[u8]) {
for &b in data {
self.write(u32::from(b), 8);
}
}
pub fn finish(self) -> Vec<u8> {
self.buf
}
}
/// `ilog` of the specification (§9.2.1): the position of the highest set bit, 0 for 0.
pub fn ilog(v: u32) -> u32 {
32 - v.leading_zeros()
}
/// The 32-bit float format of codebook headers (§9.2.2), for values it represents exactly.
pub fn float32_pack(v: f64) -> u32 {
if v == 0.0 || !v.is_finite() {
return 0;
}
let sign = if v < 0.0 { 0x8000_0000u32 } else { 0 };
let mut m = v.abs();
let mut exp: i32 = 0;
// a 21-bit mantissa: scale into [2^20, 2^21)
while m >= (1 << 21) as f64 {
m /= 2.0;
exp += 1;
}
while m < (1 << 20) as f64 {
m *= 2.0;
exp -= 1;
}
let mant = (m.round() as u32).min((1 << 21) - 1);
let biased = (exp + 788).clamp(0, 1023) as u32;
sign | (biased << 21) | mant
}
/// Huffman code lengths (1..=`max_len`) for `weights`, every entry coded.
pub fn huffman_lengths(weights: &[f64], max_len: u32) -> Vec<u32> {
let n = weights.len();
if n <= 1 {
return vec![1; n];
}
let total: f64 = weights.iter().map(|w| if w.is_finite() { w.max(0.0) } else { 0.0 }).sum::<f64>().max(1e-300);
let mut floor = 1e-9;
loop {
let w: Vec<f64> = weights.iter().map(|&x| (if x.is_finite() { x.max(0.0) } else { 0.0 }) / total + floor).collect();
let lens = huffman(&w);
if lens.iter().all(|&l| l <= max_len) || floor > 1.0 {
return lens.into_iter().map(|l| l.clamp(1, max_len)).collect();
}
floor *= 4.0;
}
}
fn huffman(w: &[f64]) -> Vec<u32> {
// nodes: (weight, children) with leaves first
let n = w.len();
let mut parent = vec![usize::MAX; 2 * n];
let mut weight: Vec<f64> = w.to_vec();
let mut alive: Vec<usize> = (0..n).collect();
while alive.len() > 1 {
alive.sort_by(|&a, &b| weight[b].partial_cmp(&weight[a]).unwrap_or(std::cmp::Ordering::Equal).then(b.cmp(&a)));
let (Some(a), Some(b)) = (alive.pop(), alive.pop()) else { break };
let id = weight.len();
weight.push(weight[a] + weight[b]);
if parent.len() <= id {
parent.resize(id + 1, usize::MAX);
}
parent[a] = id;
parent[b] = id;
alive.push(id);
}
(0..n)
.map(|i| {
let mut d = 0;
let mut x = i;
while let Some(&p) = parent.get(x) {
if p == usize::MAX {
break;
}
d += 1;
x = p;
}
d
})
.collect()
}
/// The codewords the decoder assigns to `lengths` (§3.2.1): in entry order, each entry gets the
/// lowest available codeword of its length (no prefix of an assigned codeword, and no assigned
/// codeword a prefix of it). An error when the lengths do not fit a prefix code.
pub fn assign_codewords(lengths: &[u32]) -> Result<Vec<u32>> {
// A trie of the assigned codewords: `children[node]` (0 = none), `leaf[node]`.
let mut children: Vec<[usize; 2]> = vec![[0, 0]];
let mut leaf = vec![false];
let mut words = Vec::with_capacity(lengths.len());
for &len in lengths {
if len == 0 || len > 32 {
return Err(Error::Internal("codeword length"));
}
let bits = lowest_free(&children, &leaf, 0, len).ok_or(Error::Internal("over-subscribed codebook"))?;
let mut node = 0usize;
let mut word = 0u32;
for &bit in &bits {
word = (word << 1) | bit as u32;
node = match children[node][bit] {
0 => {
children.push([0, 0]);
leaf.push(false);
let id = children.len() - 1;
children[node][bit] = id;
id
}
c => c,
};
}
leaf[node] = true;
words.push(word);
}
Ok(words)
}
/// The leftmost free path of `depth` bits below `node` (depth-first, 0 before 1).
fn lowest_free(children: &[[usize; 2]], leaf: &[bool], node: usize, depth: u32) -> Option<Vec<usize>> {
if leaf[node] || depth == 0 {
return None;
}
for bit in 0..2 {
let c = children[node][bit];
if c == 0 {
let mut p = vec![bit];
p.resize(depth as usize, 0);
return Some(p);
}
if let Some(mut rest) = lowest_free(children, leaf, c, depth - 1) {
rest.insert(0, bit);
return Some(rest);
}
}
None
}
/// A codebook: entry lengths and codewords, and for VQ books a lattice (lookup type 1).
#[derive(Clone, Debug)]
pub struct Codebook {
pub dimensions: u32,
pub lengths: Vec<u32>,
pub words: Vec<u32>,
/// Lattice values per dimension (lookup type 1: `values^dimensions == entries`).
pub lattice: Option<Lattice>,
}
#[derive(Clone, Copy, Debug)]
pub struct Lattice {
pub minimum: f64,
pub delta: f64,
/// Values per dimension.
pub values: u32,
}
impl Codebook {
/// A scalar book (no lookup) of `weights.len()` entries.
pub fn scalar(dimensions: u32, weights: &[f64]) -> Result<Codebook> {
let lengths = huffman_lengths(weights, 20);
let words = assign_codewords(&lengths)?;
Ok(Codebook { dimensions, lengths, words, lattice: None })
}
/// A lattice VQ book: `values` integers per dimension from `minimum` in steps of `delta`;
/// `weight(v)` is the relative probability of one component `v`.
pub fn lattice(dimensions: u32, values: u32, minimum: i32, delta: i32, weight: impl Fn(i32) -> f64) -> Result<Codebook> {
let entries = values.checked_pow(dimensions).ok_or(Error::Internal("codebook size"))?;
let w: Vec<f64> = (0..entries)
.map(|e| {
let mut p = 1.0;
let mut rest = e;
for _ in 0..dimensions {
let t = (rest % values) as i32;
rest /= values;
p *= weight(minimum + t * delta);
}
p
})
.collect();
let lengths = huffman_lengths(&w, 20);
let words = assign_codewords(&lengths)?;
Ok(Codebook { dimensions, lengths, words, lattice: Some(Lattice { minimum: f64::from(minimum), delta: f64::from(delta), values }) })
}
pub fn entries(&self) -> usize {
self.lengths.len()
}
/// Writes entry `e`.
pub fn put(&self, w: &mut BitWriter, e: usize) {
if let (Some(&word), Some(&len)) = (self.words.get(e), self.lengths.get(e)) {
w.codeword(word, len);
}
}
/// The entry of the lattice vector `v` (component 0 is the least significant digit, §3.2.1).
pub fn entry_of(&self, v: &[i32]) -> usize {
let Some(l) = self.lattice else { return 0 };
let mut e = 0usize;
let mut scale = 1usize;
for &x in v.iter().take(self.dimensions as usize) {
let t = ((f64::from(x) - l.minimum) / l.delta).round().clamp(0.0, f64::from(l.values - 1)) as usize;
e += t * scale;
scale *= l.values as usize;
}
e
}
/// The header encoding (§3.2.1).
pub fn write_header(&self, w: &mut BitWriter) {
w.write(0x56_4342, 24);
w.write(self.dimensions, 16);
w.write(self.entries() as u32, 24);
w.flag(false); // not ordered
w.flag(false); // not sparse
for &l in &self.lengths {
w.write(l - 1, 5);
}
match self.lattice {
None => w.write(0, 4),
Some(l) => {
w.write(1, 4);
w.write(float32_pack(l.minimum), 32);
w.write(float32_pack(l.delta), 32);
let bits = ilog(l.values - 1).max(1);
w.write(bits - 1, 4);
w.flag(false); // sequence_p
for m in 0..l.values {
w.write(m, bits);
}
}
}
}
}
+207
View File
@@ -0,0 +1,207 @@
//! Floor type 1 (Vorbis I §7): a piecewise-linear spectral envelope in the decoder's dB scale.
//!
//! The encoder picks a target value at each of the floor's X positions, codes it against the
//! decoder's prediction from its neighbours (step 2 of §7.2.4, inverted), and renders the curve
//! exactly as the decoder will (`render_line`, integer arithmetic), so the residue is computed
//! against the very floor the decoder multiplies it by.
use super::book::{BitWriter, Codebook, ilog};
/// `floor1_multiplier`: 2, so values run 0..128 and step two entries of the dB table.
pub const MULTIPLIER: u32 = 2;
/// The value range for [`MULTIPLIER`] 2.
pub const RANGE: i32 = 128;
const RANGE_BITS: u32 = 10;
/// Points per partition, and partitions.
pub const CLASS_DIM: usize = 4;
pub const PARTITIONS: usize = 8;
/// Step (in dB) between entries of `floor1_inverse_dB_table`: it runs from 1.0649863e-07 to 1
/// over 256 entries.
fn db_step() -> f64 {
(1.0f64 / 1.064_986_3e-7).ln() / 255.0
}
/// `floor1_inverse_dB_table[i]`.
pub fn inverse_db(i: i32) -> f32 {
(f64::from(i.clamp(0, 255) - 255) * db_step()).exp() as f32
}
/// The table index whose amplitude is nearest (in dB) to `a`.
pub fn db_index(a: f32) -> i32 {
if !a.is_finite() || a <= 0.0 {
return 0;
}
((f64::from(a)).ln() / db_step() + 255.0).round().clamp(0.0, 255.0) as i32
}
/// A floor 1 configuration for blocks of `n/2 = 2^RANGE_BITS` bins.
#[derive(Clone, Debug)]
pub struct Floor1 {
/// X positions: 0, 1024, then the partitions' points.
pub xs: Vec<i32>,
/// Index of the book coding the point values.
pub book: usize,
/// For each point (in coding order) its low and high neighbours.
neighbours: Vec<(usize, usize)>,
/// Point indices sorted by X.
sorted: Vec<usize>,
}
impl Floor1 {
/// Points spaced about evenly in log frequency over 1..1024.
pub fn new(book: usize) -> Floor1 {
let count = CLASS_DIM * PARTITIONS;
let mut xs = vec![0, 1 << RANGE_BITS];
let mut last = 0;
for i in 1..=count {
// geometric from 2 to ~1000 bins, at least one bin apart
let x = (2.0f64 * (500.0f64).powf((i - 1) as f64 / (count - 1) as f64)).round() as i32;
let x = x.max(last + 1).min((1 << RANGE_BITS) - 1);
xs.push(x);
last = x;
}
let neighbours = (0..xs.len())
.map(|i| {
if i < 2 {
return (0, 0);
}
let (mut lo, mut hi) = (0usize, 1usize);
for j in 0..i {
if xs[j] < xs[i] && xs[j] > xs[lo] {
lo = j;
}
if xs[j] > xs[i] && xs[j] < xs[hi] {
hi = j;
}
}
(lo, hi)
})
.collect();
let mut sorted: Vec<usize> = (0..xs.len()).collect();
sorted.sort_by_key(|&i| xs[i]);
Floor1 { xs, book, neighbours, sorted }
}
/// The setup-header encoding (§7.2.2): one class of `CLASS_DIM` points, no subclasses.
pub fn write_header(&self, w: &mut BitWriter) {
w.write(PARTITIONS as u32, 5);
for _ in 0..PARTITIONS {
w.write(0, 4);
}
w.write(CLASS_DIM as u32 - 1, 3);
w.write(0, 2); // no subclasses
w.write(self.book as u32 + 1, 8);
w.write(MULTIPLIER - 1, 2);
w.write(RANGE_BITS, 4);
for &x in &self.xs[2..] {
w.write(x as u32, RANGE_BITS);
}
}
/// Codes the target values `want` (one per point, 0..RANGE) into `w`; returns the floor curve
/// the decoder renders (`n2` amplitudes).
pub fn encode(&self, w: &mut BitWriter, book: &Codebook, want: &[i32], n2: usize) -> Vec<f32> {
let n = self.xs.len();
let want = |i: usize| want.get(i).copied().unwrap_or(0).clamp(0, RANGE - 1);
let mut fin = vec![0i32; n];
let mut used = vec![false; n];
let mut coded = vec![0u32; n];
fin[0] = want(0);
fin[1] = want(1);
used[0] = true;
used[1] = true;
for i in 2..n {
let (lo, hi) = self.neighbours[i];
let pred = render_point(self.xs[lo], fin[lo], self.xs[hi], fin[hi], self.xs[i]);
let f = want(i);
let (highroom, lowroom) = (RANGE - pred, pred);
let room = 2 * highroom.min(lowroom);
let val = if f == pred {
0
} else {
let d = f - pred;
let inside = if d > 0 { 2 * d } else { -2 * d - 1 };
if inside < room {
inside
} else if highroom > lowroom {
f - pred + lowroom
} else {
pred - f + highroom - 1
}
};
coded[i] = val.clamp(0, RANGE - 1) as u32;
if val != 0 {
used[lo] = true;
used[hi] = true;
used[i] = true;
fin[i] = f;
} else {
fin[i] = pred;
}
}
let bits = ilog(RANGE as u32 - 1);
w.write(fin[0] as u32, bits);
w.write(fin[1] as u32, bits);
for &c in &coded[2..] {
book.put(w, c as usize);
}
self.render(&fin, &used, n2)
}
/// The decoder's curve (§7.2.4 step 2, `render_line`) as amplitudes.
fn render(&self, fin: &[i32], used: &[bool], n2: usize) -> Vec<f32> {
let mut v = vec![0i32; n2];
let m = MULTIPLIER as i32;
let (mut lx, mut ly) = (0i32, fin[self.sorted[0]] * m);
let (mut hx, mut hy) = (0i32, ly);
for &i in &self.sorted[1..] {
if used[i] {
hy = fin[i] * m;
hx = self.xs[i];
render_line(lx, ly, hx, hy, &mut v);
lx = hx;
ly = hy;
}
}
if (hx as usize) < n2 {
render_line(hx, hy, n2 as i32, hy, &mut v);
}
v.iter().map(|&i| inverse_db(i)).collect()
}
}
fn render_point(x0: i32, y0: i32, x1: i32, y1: i32, x: i32) -> i32 {
let dy = y1 - y0;
let adx = (x1 - x0).max(1);
let err = dy.abs() * (x - x0);
let off = err / adx;
if dy < 0 { y0 - off } else { y0 + off }
}
fn render_line(x0: i32, y0: i32, x1: i32, y1: i32, v: &mut [i32]) {
let dy = y1 - y0;
let adx = x1 - x0;
if adx <= 0 {
return;
}
let base = dy / adx;
let sy = if dy < 0 { base - 1 } else { base + 1 };
let ady = dy.abs() - base.abs() * adx;
let (mut y, mut err) = (y0, 0);
if let Some(s) = v.get_mut(x0 as usize) {
*s = y;
}
for x in x0 + 1..x1 {
err += ady;
if err >= adx {
err -= adx;
y += sy;
} else {
y += base;
}
if let Some(s) = v.get_mut(x as usize) {
*s = y;
}
}
}
+134
View File
@@ -0,0 +1,134 @@
//! Forward MDCT of a windowed block of `n` samples to `n/2` coefficients:
//! `X[k] = Σ x[j] cos(2π/n · (j + 1/2 + n/4)(k + 1/2))`, the transform the Vorbis decoder inverts
//! (Vorbis I §1.3.2, §4.3.9). Computed as a DCT-IV of the folded block through an `n/8`-point
//! complex FFT.
use std::f64::consts::PI;
#[derive(Clone, Copy, Default, Debug)]
struct Cpx {
re: f64,
im: f64,
}
impl Cpx {
fn mul(self, o: Cpx) -> Cpx {
Cpx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re }
}
}
/// A forward MDCT for one block size (a power of two, at least 16).
#[derive(Clone, Debug)]
pub struct Mdct {
n: usize,
twiddle: Vec<Cpx>,
post: Vec<Cpx>,
fft_tw: Vec<Cpx>,
rev: Vec<usize>,
}
impl Mdct {
pub fn new(n: usize) -> Mdct {
let m = n / 2; // DCT-IV length
let h = m / 2; // FFT length
let twiddle = (0..h).map(|j| cis(-PI * (4.0 * j as f64 + 1.0) / (4.0 * m as f64))).collect();
let post = (0..h).map(|k| cis(-PI * k as f64 / m as f64)).collect();
let fft_tw = (0..h / 2).map(|j| cis(-2.0 * PI * j as f64 / h as f64)).collect();
let bits = h.trailing_zeros();
let rev = (0..h).map(|i| if bits == 0 { 0 } else { i.reverse_bits() >> (usize::BITS - bits) }).collect();
Mdct { n, twiddle, post, fft_tw, rev }
}
/// `x`: `n` windowed samples; `out`: `n/2` coefficients (scaled by `scale`).
pub fn forward(&self, x: &[f32], out: &mut [f32], scale: f64) {
let n = self.n;
let m = n / 2;
let q = n / 4;
let at = |i: usize| f64::from(x.get(i).copied().unwrap_or(0.0));
// fold (a, b, c, d) to the DCT-IV input (-c_r - d, a - b_r)
let mut v = vec![0f64; m];
for (i, s) in v.iter_mut().enumerate() {
*s = if i < q { -at(3 * q - 1 - i) - at(3 * q + i) } else { at(i - q) - at(3 * q - 1 - i) };
}
// DCT-IV through a half-length complex FFT
let h = m / 2;
let mut z: Vec<Cpx> = (0..h).map(|j| Cpx { re: v[2 * j], im: v[m - 1 - 2 * j] }.mul(self.twiddle[j])).collect();
self.fft(&mut z);
for (k, c) in z.iter().enumerate() {
let d = c.mul(self.post[k]);
if let Some(o) = out.get_mut(2 * k) {
*o = (d.re * scale) as f32;
}
if let Some(o) = out.get_mut(m - 1 - 2 * k) {
*o = (-d.im * scale) as f32;
}
}
}
/// In-place radix-2 FFT (`e^{-2πi jk/h}`).
fn fft(&self, a: &mut [Cpx]) {
let h = a.len();
for i in 0..h {
let j = self.rev[i];
if i < j {
a.swap(i, j);
}
}
let mut len = 2;
while len <= h {
let step = h / len;
for start in (0..h).step_by(len) {
for k in 0..len / 2 {
let w = self.fft_tw[k * step];
let u = a[start + k];
let t = a[start + k + len / 2].mul(w);
a[start + k] = Cpx { re: u.re + t.re, im: u.im + t.im };
a[start + k + len / 2] = Cpx { re: u.re - t.re, im: u.im - t.im };
}
}
len *= 2;
}
}
}
fn cis(t: f64) -> Cpx {
Cpx { re: t.cos(), im: t.sin() }
}
/// The Vorbis window (§4.3.1) for a block of `n` between blocks of the same size.
pub fn window(n: usize) -> Vec<f32> {
(0..n)
.map(|i| {
let s = (PI * (i as f64 + 0.5) / n as f64).sin();
(PI / 2.0 * s * s).sin() as f32
})
.collect()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn matches_the_direct_formula() {
for n in [16usize, 64, 256, 2048] {
let x: Vec<f32> = (0..n).map(|i| ((i * 7919 % 211) as f32 - 105.0) / 50.0).collect();
let mut fast = vec![0f32; n / 2];
Mdct::new(n).forward(&x, &mut fast, 1.0);
for k in [0usize, 1, 2, n / 4, n / 2 - 1] {
let direct: f64 =
(0..n).map(|j| f64::from(x[j]) * (2.0 * PI / n as f64 * (j as f64 + 0.5 + n as f64 / 4.0) * (k as f64 + 0.5)).cos()).sum();
assert!((direct - f64::from(fast[k])).abs() < 1e-3 * (1.0 + direct.abs()), "n={n} k={k}: {direct} vs {}", fast[k]);
}
}
}
#[test]
fn the_window_is_power_complementary() {
let w = window(2048);
for i in 0..1024 {
let s = w[i] * w[i] + w[i + 1024] * w[i + 1024];
assert!((s - 1.0).abs() < 1e-5, "{i}: {s}");
}
}
}
+494
View File
@@ -0,0 +1,494 @@
//! Pure-Rust Vorbis I encoder, written from the Vorbis I specification (Xiph.Org, 2020-07-04).
//!
//! No `unsafe` and no C code; builds for `wasm32-unknown-unknown`. ffmpeg is used only as an
//! external test oracle.
//!
//! The stream: one mode of 2048-sample blocks; per channel a floor 1 envelope of 34 points; one
//! residue type 2 over the interleaved channels, partitions of 32 values (a multiple of the
//! channel count for 3, 5, 6 and 7 channels) in seven classes (silent,
//! three single-pass lattice books, and two- and three-pass cascades for large values); no channel
//! coupling. Quality (-1 to 10) sets how far the floor sits from the spectral envelope (below it
//! for tonal regions, above it for noise-like ones, from the spectral flatness), and with it the
//! residue's precision: variable bit rate, like other Vorbis encoders.
//!
//! From FilmCraft's `filmcraft-vorbis` by @JordyUSA (storytold/filmcraft#4481).
//!
//! The packets go into Ogg with [`craft_media::ogg::PageWriter`] and a comment header from
//! [`craft_media::ogg::vorbis_comment`]; [`crate::encode_ogg_vorbis`] does all of it for a
//! whole buffer.
//!
//! ```
//! use craft_audio::vorbis::encoder::{Encoder, EncoderConfig};
//!
//! let mut enc = Encoder::new(EncoderConfig::new(48_000, 2, 5.0))?;
//! let tone: Vec<f32> = (0..4_800).map(|i| (i as f32 * 0.05).sin() * 0.5).collect();
//! let mut packets = enc.encode(&[&tone, &tone])?;
//! packets.extend(enc.finish()?);
//! // the last granule position is the input's length, so a decoder trims the padding
//! assert_eq!(packets.last().map(|p| p.1), Some(4_800));
//! assert_eq!(&enc.identification()[1..7], b"vorbis");
//! # Ok::<(), craft_audio::vorbis::encoder::Error>(())
//! ```
// Index loops follow the specification, as in FilmCraft (which allows this lint workspace-wide).
#![allow(clippy::needless_range_loop)]
mod book;
mod floor;
mod mdct;
use book::{BitWriter, Codebook};
use floor::Floor1;
use mdct::Mdct;
/// Why an encoder could not be created or input could not be encoded.
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
pub enum Error {
/// A setting or the input is outside what the encoder takes.
#[error("invalid argument: {0}")]
InvalidArgument(&'static str),
/// An encoder invariant failed (a bug, reported instead of panicking).
#[error("internal error: {0}")]
Internal(&'static str),
}
/// The encoder's result type.
pub type Result<T> = std::result::Result<T, Error>;
/// Block size (samples); the short block size of the header is never used.
pub const BLOCK: usize = 2048;
const HOP: usize = BLOCK / 2;
/// Residue values per partition for `channels` channels: 32, or for 3, 5, 6 and 7 channels a
/// multiple of the channel count (48, 40, 48, 56). libvorbis decodes each partition of an
/// interleaved (type 2) residue as if it started on channel 0, so a partition must hold whole
/// sample frames; the size also divides `channels × 1024` and is a multiple of every book's
/// dimension (4).
fn partition_size(channels: usize) -> usize {
match channels {
3 | 6 => 48,
5 => 40,
7 => 56,
_ => 32,
}
}
const CLASSES: usize = 8;
/// Largest residue magnitude the cascade codes: 7·225 + 7·15 + 7.
const MAX_RESIDUE: i32 = 1687;
/// The quality a NaN or infinite setting reads as.
pub const DEFAULT_QUALITY: f32 = 6.0;
/// Encoder settings.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct EncoderConfig {
/// Samples per second, 1 to 768 000.
pub sample_rate: u32,
/// 1 to 8, in Vorbis channel order (§4.3.9).
pub channels: usize,
/// -1 (smallest) to 10 (best); clamped.
pub quality: f32,
}
impl EncoderConfig {
/// Settings for `channels` channels (in Vorbis order) at `sample_rate` and `quality`.
pub fn new(sample_rate: u32, channels: usize, quality: f32) -> EncoderConfig {
EncoderConfig { sample_rate, channels, quality }
}
}
/// Book indices in the setup header.
const BOOK_CLASS: usize = 0;
const BOOK_FLOOR: usize = 1;
const BOOK_A1_SPARSE: usize = 2;
const BOOK_A1: usize = 3;
const BOOK_A2: usize = 4;
const BOOK_A4: usize = 5;
const BOOK_F: usize = 6;
const BOOK_M: usize = 7;
const BOOK_C: usize = 8;
/// Books per class and pass (`None`: nothing coded in that pass).
const CASCADE: [[Option<usize>; 3]; CLASSES] = [
[None, None, None],
[Some(BOOK_A1_SPARSE), None, None],
[Some(BOOK_A1), None, None],
[Some(BOOK_A2), None, None],
[Some(BOOK_A4), None, None],
[Some(BOOK_F), None, None],
[Some(BOOK_M), Some(BOOK_F), None],
[Some(BOOK_C), Some(BOOK_M), Some(BOOK_F)],
];
/// A Vorbis encoder for one stream: planar `f32` in, Vorbis packets with their granule
/// positions out.
pub struct Encoder {
cfg: EncoderConfig,
books: Vec<Codebook>,
floor: Floor1,
mdct: Mdct,
window: Vec<f32>,
/// Input not yet past a block, per channel; the next block starts at `start`.
pending: Vec<Vec<f32>>,
/// Read cursor into `pending`: consumed hops are dropped once per call, not per block.
start: usize,
samples_in: u64,
blocks: u64,
finished: bool,
/// Floor offset below the envelope (dB) for tonal and for noise-like regions.
tonal_db: f32,
noise_db: f32,
/// Residue magnitudes below this quantise to 0.
dead_zone: f32,
}
impl Encoder {
/// An encoder for `cfg`: 1 to 8 channels, a sample rate of 1 to 768 000; the quality is
/// clamped to -1..=10, and NaN or infinite reads as [`DEFAULT_QUALITY`].
pub fn new(cfg: EncoderConfig) -> Result<Encoder> {
if !(1..=8).contains(&cfg.channels) {
return Err(Error::InvalidArgument("Vorbis encoder: 1 to 8 channels"));
}
if !(1..=768_000).contains(&cfg.sample_rate) {
return Err(Error::InvalidArgument("Vorbis encoder: sample rate"));
}
let quality = if cfg.quality.is_finite() { cfg.quality.clamp(-1.0, 10.0) } else { DEFAULT_QUALITY };
let cfg = EncoderConfig { quality, ..cfg };
let books = vec![
Codebook::scalar(2, &(0..CLASSES * CLASSES).map(|e| class_weight(e / CLASSES) * class_weight(e % CLASSES)).collect::<Vec<_>>())?,
Codebook::scalar(1, &(0..floor::RANGE).map(|v| 1.0 / (1.0 + f64::from(v)).powf(1.6)).collect::<Vec<_>>())?,
Codebook::lattice(4, 3, -1, 1, |v| if v == 0 { 0.92 } else { 0.04 })?,
Codebook::lattice(4, 3, -1, 1, |v| if v == 0 { 0.5 } else { 0.25 })?,
Codebook::lattice(2, 5, -2, 1, |v| 0.6f64.powi(v.abs()))?,
Codebook::lattice(2, 9, -4, 1, |v| 0.7f64.powi(v.abs()))?,
Codebook::lattice(2, 15, -7, 1, |v| 0.8f64.powi(v.abs()))?,
Codebook::lattice(2, 15, -105, 15, |v| 0.55f64.powi((v / 15).abs()))?,
Codebook::lattice(2, 15, -1575, 225, |v| 0.4f64.powi((v / 225).abs()))?,
];
Ok(Encoder {
cfg,
books,
floor: Floor1::new(BOOK_FLOOR),
mdct: Mdct::new(BLOCK),
window: mdct::window(BLOCK),
// the first block is centred on sample 0: the decoder's first output is input sample 0
pending: vec![vec![0.0; HOP]; cfg.channels],
start: 0,
samples_in: 0,
blocks: 0,
finished: false,
// tones 4 dB (-1) to 30.4 dB (10) under their envelope; noise 14 dB above it (-1)
// to 4.1 dB (10)
tonal_db: 4.0 + 2.4 * (quality + 1.0),
noise_db: -14.0 + 0.9 * (quality + 1.0),
dead_zone: 0.8 - 0.025 * (quality + 1.0),
})
}
/// Channels per sample frame.
pub fn channels(&self) -> usize {
self.cfg.channels
}
/// The quality in use, after clamping.
pub fn quality(&self) -> f32 {
self.cfg.quality
}
/// Input samples per channel taken so far.
pub fn samples_in(&self) -> u64 {
self.samples_in
}
/// The identification header packet (§4.2.2): the first packet of the stream.
pub fn identification(&self) -> Vec<u8> {
let mut w = BitWriter::new();
w.write(1, 8);
w.bytes(b"vorbis");
w.write(0, 32);
w.write(self.cfg.channels as u32, 8);
w.write(self.cfg.sample_rate, 32);
w.write(0, 32); // bit rates: unset (variable)
w.write(0, 32);
w.write(0, 32);
w.write(8, 4); // 256-sample short blocks (unused)
w.write(11, 4); // 2048-sample long blocks
w.flag(true);
w.finish()
}
/// The setup header packet (§4.2.4): codebooks, floor, residue, mapping and mode. It follows
/// the comment header.
pub fn setup(&self) -> Vec<u8> {
let mut w = BitWriter::new();
w.write(5, 8);
w.bytes(b"vorbis");
w.write(self.books.len() as u32 - 1, 8);
for b in &self.books {
b.write_header(&mut w);
}
w.write(0, 6); // one time-domain transform placeholder
w.write(0, 16);
w.write(0, 6); // one floor
w.write(1, 16);
self.floor.write_header(&mut w);
w.write(0, 6); // one residue, type 2
w.write(2, 16);
let end = (self.cfg.channels * HOP) as u32;
w.write(0, 24);
w.write(end, 24);
w.write(partition_size(self.cfg.channels) as u32 - 1, 24);
w.write(CLASSES as u32 - 1, 6);
w.write(BOOK_CLASS as u32, 8);
for c in &CASCADE {
let bits: u32 = c.iter().enumerate().map(|(j, b)| u32::from(b.is_some()) << j).sum();
w.write(bits & 7, 3);
w.flag(bits > 7);
if bits > 7 {
w.write(bits >> 3, 5);
}
}
for c in &CASCADE {
for b in c.iter().flatten() {
w.write(*b as u32, 8);
}
}
w.write(0, 6); // one mapping, type 0
w.write(0, 16);
w.flag(false); // one submap
w.flag(false); // no coupling
w.write(0, 2);
w.write(0, 8); // submap 0: time, floor 0, residue 0
w.write(0, 8);
w.write(0, 8);
w.write(0, 6); // one mode: long blocks, mapping 0
w.flag(true);
w.write(0, 16);
w.write(0, 16);
w.write(0, 8);
w.flag(true);
w.finish()
}
/// Encodes planar samples (one slice per channel, all the same length, nominal range ±1);
/// returns the packets completed with their granule positions. NaN or infinite samples, or a
/// channel count or length mismatch, are an error.
pub fn encode(&mut self, planar: &[&[f32]]) -> Result<Vec<(Vec<u8>, i64)>> {
if self.finished {
return Err(Error::InvalidArgument("Vorbis encoder: encode after finish"));
}
if planar.len() != self.cfg.channels {
return Err(Error::InvalidArgument("Vorbis encoder: one slice per channel"));
}
let len = planar.first().map_or(0, |p| p.len());
if planar.iter().any(|p| p.len() != len) {
return Err(Error::InvalidArgument("Vorbis encoder: channels of different lengths"));
}
if planar.iter().any(|p| p.iter().any(|v| !v.is_finite())) {
return Err(Error::InvalidArgument("Vorbis encoder: NaN or infinite sample"));
}
for (b, p) in self.pending.iter_mut().zip(planar) {
b.extend_from_slice(p);
}
self.samples_in += len as u64;
self.drain()
}
/// Encodes what remains, padded with silence; the last packet's granule position is the
/// input's length, so the decoder trims the padding (§A.2).
pub fn finish(&mut self) -> Result<Vec<(Vec<u8>, i64)>> {
if self.finished {
return Ok(Vec::new());
}
self.finished = true;
// block k ends output at k·HOP: blocks 0..=ceil(len / HOP)
let blocks = self.samples_in.div_ceil(HOP as u64) + 1;
let missing = blocks.saturating_sub(self.blocks) as usize;
self.compact();
let need = (missing + 1) * HOP;
for b in self.pending.iter_mut() {
if b.len() < need {
b.resize(need, 0.0);
}
}
let mut out = Vec::new();
for _ in 0..missing {
out.push(self.block()?);
}
Ok(out)
}
fn drain(&mut self) -> Result<Vec<(Vec<u8>, i64)>> {
let mut out = Vec::new();
while self.pending.first().is_some_and(|b| b.len().saturating_sub(self.start) >= BLOCK) {
out.push(self.block()?);
}
self.compact();
Ok(out)
}
/// Drops the hops already encoded from the front of every channel buffer.
fn compact(&mut self) {
for b in self.pending.iter_mut() {
b.drain(..self.start.min(b.len()));
}
self.start = 0;
}
/// Encodes the block at `start` in `pending` and advances by a hop.
fn block(&mut self) -> Result<(Vec<u8>, i64)> {
let ch = self.cfg.channels;
let mut w = BitWriter::new();
w.write(0, 1); // audio packet; one mode, so no mode number
w.flag(true); // previous and next windows long
w.flag(true);
let mut residue = vec![0i32; ch * HOP];
let mut any = false;
let mut x = vec![0f32; BLOCK];
let mut coeffs = vec![0f32; HOP];
for c in 0..ch {
let src = self.pending.get(c).and_then(|b| b.get(self.start..)).ok_or(Error::Internal("channel buffer"))?;
for (i, v) in x.iter_mut().enumerate() {
*v = src.get(i).copied().unwrap_or(0.0).clamp(-8.0, 8.0) * self.window[i];
}
self.mdct.forward(&x, &mut coeffs, 2.0 / HOP as f64);
let peak = coeffs.iter().fold(0f32, |m, v| m.max(v.abs()));
// (a NaN peak cannot happen: samples are finite and clamped)
if peak <= 1e-7 {
w.flag(false); // floor unused: the channel is silent
continue;
}
any = true;
w.flag(true);
let want = self.floor_targets(&coeffs);
let curve = self.floor.encode(&mut w, &self.books[BOOK_FLOOR], &want, HOP);
for (k, (&v, &f)) in coeffs.iter().zip(&curve).enumerate() {
let r = if f > 0.0 { v / f } else { 0.0 };
// a dead zone: values just past half a step are noise peaks, not worth a ±1
let q = if r.abs() < self.dead_zone { 0.0 } else { r.round() };
residue[k * ch + c] = if q.is_finite() { (q as i32).clamp(-MAX_RESIDUE, MAX_RESIDUE) } else { 0 };
}
}
if any {
self.write_residue(&mut w, &residue);
}
let granule = if self.blocks == 0 {
0
} else {
let natural = self.blocks.saturating_mul(HOP as u64);
if self.finished { natural.min(self.samples_in) } else { natural }
};
self.start += HOP;
self.blocks += 1;
Ok((w.finish(), i64::try_from(granule).unwrap_or(i64::MAX)))
}
/// Floor values at the floor's points: the spectral envelope (power smoothed over a quarter of
/// the frequency, at least 8 bins, on each side) less an offset that grows with the region's tonality, from its
/// spectral flatness: noise needs a few dB of precision, tones much more.
fn floor_targets(&self, coeffs: &[f32]) -> Vec<i32> {
let n = coeffs.len();
let mut cum = vec![0f64; n + 1];
let mut cum_ln = vec![0f64; n + 1];
for (i, &v) in coeffs.iter().enumerate() {
let p = f64::from(v) * f64::from(v);
cum[i + 1] = cum[i] + p;
cum_ln[i + 1] = cum_ln[i] + (p + 1e-30).ln();
}
self.floor
.xs
.iter()
.map(|&x| {
let k = (x as usize).min(n - 1);
let half = (k / 4).max(8);
let (lo, hi) = (k.saturating_sub(half), (k + half + 1).min(n));
let len = (hi - lo) as f64;
let am = (cum[hi] - cum[lo]) / len;
let gm = ((cum_ln[hi] - cum_ln[lo]) / len).exp();
// spectral flatness: about -2.5 dB for noise, far below for a tone
let sfm_db = 10.0 * (gm / am.max(1e-30)).max(1e-30).log10();
let tonality = ((-sfm_db - 2.5) / 20.0).clamp(0.0, 1.0);
let offset = tonality * f64::from(self.tonal_db) + (1.0 - tonality) * f64::from(self.noise_db);
let amp = (am.sqrt() * 10f64.powf(-offset / 20.0)).max(1e-7) as f32;
(floor::db_index(amp) + 1) / floor::MULTIPLIER as i32
})
.collect()
}
/// Residue type 2 (§8.6.2 with the interleaved vector): classes per partition, then the
/// cascade's passes in the decoder's order.
fn write_residue(&self, w: &mut BitWriter, r: &[i32]) {
let partition = partition_size(self.cfg.channels);
let parts = r.len() / partition;
let classes: Vec<usize> = r.chunks(partition).map(class_of).collect();
let per_word = self.books[BOOK_CLASS].dimensions as usize;
for pass in 0..3 {
let mut pc = 0;
while pc < parts {
if pass == 0 {
let mut e = 0usize;
for i in 0..per_word {
e = e * CLASSES + classes.get(pc + i).copied().unwrap_or(0);
}
self.books[BOOK_CLASS].put(w, e);
}
for _ in 0..per_word {
if pc >= parts {
break;
}
let class = classes[pc];
if let Some(b) = CASCADE[class][pass] {
let book = &self.books[b];
let dims = book.dimensions as usize;
let part = &r[pc * partition..(pc + 1) * partition];
for chunk in part.chunks(dims) {
let v: Vec<i32> = chunk.iter().map(|&x| pass_value(x, class, pass)).collect();
book.put(w, book.entry_of(&v));
}
}
pc += 1;
}
}
}
}
}
/// Relative frequency of each residue class (for the class book's code lengths).
fn class_weight(c: usize) -> f64 {
[0.3, 0.2, 0.12, 0.12, 0.1, 0.08, 0.06, 0.02].get(c).copied().unwrap_or(0.01)
}
/// The part of residue value `v` coded in `pass` for `class`: the passes add up to `v`.
fn pass_value(v: i32, class: usize, pass: usize) -> i32 {
let split = |v: i32, step: i32| -> (i32, i32) {
let a = ((f64::from(v) / f64::from(step)).round() as i32).clamp(-7, 7);
(a * step, v - a * step)
};
match (class, pass) {
(6, 0) => split(v, 15).0,
(6, _) => split(v, 15).1,
(7, 0) => split(v, 225).0,
(7, 1) => split(split(v, 225).1, 15).0,
(7, _) => split(split(v, 225).1, 15).1,
_ => v,
}
}
/// The residue class of a partition: silent; ±1 with at most four nonzero values, or more; then
/// by the largest magnitude.
fn class_of(p: &[i32]) -> usize {
let m = p.iter().map(|v| v.abs()).max().unwrap_or(0);
match m {
0 => 0,
1 if p.iter().filter(|&&v| v != 0).count() <= 4 => 1,
1 => 2,
2 => 3,
3..=4 => 4,
5..=7 => 5,
8..=112 => 6,
_ => 7,
}
}
#[cfg(test)]
mod tests;
+285
View File
@@ -0,0 +1,285 @@
//! Unit tests, and ffmpeg (as an external oracle only) decoding the encoder's streams.
#![allow(clippy::unwrap_used)]
use std::path::Path;
use std::process::Command;
use super::book::{BitWriter, assign_codewords, float32_pack};
use super::{BLOCK, Encoder, EncoderConfig, HOP, partition_size};
#[test]
fn codewords_follow_the_specification_example() {
// Vorbis I §3.2.1: lengths 2 4 4 4 4 2 3 3
let words = assign_codewords(&[2, 4, 4, 4, 4, 2, 3, 3]).unwrap();
assert_eq!(words, [0b00, 0b0100, 0b0101, 0b0110, 0b0111, 0b10, 0b110, 0b111]);
assert!(assign_codewords(&[1, 1, 1]).is_err(), "over-subscribed");
}
#[test]
fn every_book_is_a_complete_prefix_code() {
let e = Encoder::new(EncoderConfig::new(48_000, 2, 5.0)).unwrap();
for (i, b) in e.books.iter().enumerate() {
let kraft: f64 = b.lengths.iter().map(|&l| 0.5f64.powi(l as i32)).sum();
assert!((kraft - 1.0).abs() < 1e-9, "book {i}: Kraft sum {kraft}");
assert!(b.lengths.iter().all(|&l| (1..=20).contains(&l)));
for (a, (&wa, &la)) in b.words.iter().zip(&b.lengths).enumerate() {
for (c, (&wc, &lc)) in b.words.iter().zip(&b.lengths).enumerate() {
if a != c && la <= lc {
assert_ne!(wc >> (lc - la), wa, "book {i}: codeword {a} is a prefix of {c}");
}
}
}
}
}
#[test]
fn float32_pack_is_exact_for_lattice_values() {
let unpack = |x: u32| {
let mant = f64::from(x & 0x1F_FFFF);
let exp = ((x >> 21) & 0x3FF) as i32 - 788;
let v = mant * 2f64.powi(exp);
if x & 0x8000_0000 != 0 { -v } else { v }
};
for v in [1.0, -1.0, -2.0, -4.0, -7.0, -105.0, 15.0, -1575.0, 225.0, 0.5, 3.0] {
assert_eq!(unpack(float32_pack(v)), v);
}
assert_eq!(float32_pack(0.0), 0);
}
#[test]
fn bits_are_packed_lsb_first() {
let mut w = BitWriter::new();
w.write(0b1, 1);
w.write(0b10, 2);
w.write(0x1F, 5);
w.write(0xABC, 12);
assert_eq!(w.finish(), [0b1111_1101, 0xBC, 0x0A]);
}
#[test]
fn hostile_input_is_an_error_not_a_panic() {
assert!(Encoder::new(EncoderConfig::new(48_000, 0, 3.0)).is_err());
assert!(Encoder::new(EncoderConfig::new(48_000, 9, 3.0)).is_err());
assert!(Encoder::new(EncoderConfig::new(0, 2, 3.0)).is_err());
assert_eq!(Encoder::new(EncoderConfig::new(48_000, 1, f32::NAN)).unwrap().cfg.quality, 6.0, "NaN quality uses the default, as the export does");
let mut e = Encoder::new(EncoderConfig::new(44_100, 2, 3.0)).unwrap();
assert!(e.encode(&[&[0.0; 4]]).is_err());
assert!(e.encode(&[&[0.0; 4], &[0.0; 3]]).is_err());
assert!(e.encode(&[&[f32::NAN; 4], &[0.0; 4]]).is_err());
let loud = vec![1e30f32; 5000];
assert!(!e.encode(&[&loud, &loud]).unwrap().is_empty());
assert!(!e.finish().unwrap().is_empty());
assert!(e.finish().unwrap().is_empty());
assert!(e.encode(&[&[0.0; 4], &[0.0; 4]]).is_err());
}
#[test]
fn granules_count_the_samples_and_trim_the_end() {
for len in [0usize, 1, 1023, 1024, 1025, 48_000] {
let mut e = Encoder::new(EncoderConfig::new(48_000, 1, 3.0)).unwrap();
let x = vec![0.1f32; len];
let mut packets = e.encode(&[&x]).unwrap();
packets.extend(e.finish().unwrap());
assert_eq!(packets.len(), len.div_ceil(HOP) + 1, "len {len}");
// packet k ends output at k·1024 samples; the last one at the input's length
let want: Vec<i64> = (0..packets.len()).map(|k| ((k * HOP) as i64).min(len as i64)).collect();
let got: Vec<i64> = packets.iter().map(|p| p.1).collect();
assert_eq!(got, want, "len {len}");
}
}
// --- ffmpeg oracle ---
/// An Ogg Vorbis file of the three headers and the audio packets, through craft-media's writer.
fn ogg(packets: &[(Vec<u8>, i64)]) -> Vec<u8> {
let mut w = craft_media::ogg::PageWriter::new(7);
let mut out = Vec::new();
for (i, (p, g)) in packets.iter().enumerate() {
out.extend(if i < 3 { w.header(p) } else { w.packet(p, *g) });
}
out.extend(w.finish(None));
out
}
fn comment() -> Vec<u8> {
craft_media::ogg::vorbis_comment("test", &[])
}
/// Encodes `input` (planar) and decodes it with ffmpeg's `decoder`; returns the planar output.
/// ffmpeg's decoders to check: its own `vorbis` always, and `libvorbis` when ffmpeg has it.
fn decoders(ff: &Path) -> Vec<&'static str> {
let list =
Command::new(ff).args(["-hide_banner", "-decoders"]).output().map(|o| String::from_utf8_lossy(&o.stdout).into_owned()).unwrap_or_default();
if list.lines().any(|l| l.split_whitespace().nth(1) == Some("libvorbis")) {
vec!["vorbis", "libvorbis"]
} else {
eprintln!("SKIPPED (libvorbis decoder): this ffmpeg has no libvorbis; checking its own decoder only");
vec!["vorbis"]
}
}
fn round_trip(input: &[Vec<f32>], rate: u32, quality: f32, decoder: &str, name: &str) -> Option<(Vec<Vec<f32>>, usize)> {
let ff = craft_media_testkit::ffmpeg_or_skip("vorbis oracle")?;
let mut e = Encoder::new(EncoderConfig::new(rate, input.len(), quality)).unwrap();
let mut packets = vec![(e.identification(), 0), (comment(), 0), (e.setup(), 0)];
let n = input[0].len();
let mut at = 0;
while at < n {
let end = (at + 4410).min(n);
let s: Vec<&[f32]> = input.iter().map(|c| &c[at..end]).collect();
packets.extend(e.encode(&s).unwrap());
at = end;
}
packets.extend(e.finish().unwrap());
let bytes: usize = packets[3..].iter().map(|p| p.0.len()).sum();
let dir = craft_media_testkit::fixtures_dir("audio/vorbis-encoder");
let path = dir.join(format!("{name}.ogg"));
std::fs::write(&path, ogg(&packets)).unwrap();
let out = Command::new(ff)
.args(["-v", "error", "-xerror", "-c:a", decoder, "-i"])
.arg(&path)
.args(["-f", "f32le", "-c:a", "pcm_f32le", "-"])
.output()
.unwrap();
assert!(out.status.success() && out.stderr.is_empty(), "{name} {decoder}: {}", String::from_utf8_lossy(&out.stderr));
let pcm: Vec<f32> = out.stdout.as_chunks::<4>().0.iter().map(|&b| f32::from_le_bytes(b)).collect();
let ch = input.len();
Some(((0..ch).map(|c| pcm.iter().skip(c).step_by(ch).copied().collect()).collect(), bytes))
}
fn snr_db(a: &[f32], b: &[f32]) -> f64 {
let (mut s, mut e) = (0f64, 0f64);
for (&x, &y) in a.iter().zip(b) {
s += f64::from(x) * f64::from(x);
e += (f64::from(x) - f64::from(y)).powi(2);
}
10.0 * (s.max(1e-20) / e.max(1e-20)).log10()
}
fn music(n: usize, seed: u32) -> Vec<f32> {
let mut r = seed;
(0..n)
.map(|i| {
let t = i as f32 / 48_000.0;
r = r.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
let noise = (r >> 8) as f32 / 8_388_608.0 - 1.0;
let chord: f32 = [220.0f32, 277.18, 329.63, 440.0]
.iter()
.enumerate()
.map(|(k, f)| (0.2 / (k + 1) as f32) * (2.0 * std::f32::consts::PI * f * t).sin())
.sum();
chord + 0.01 * noise
})
.collect()
}
/// Harmonic chords changing every half second, with decaying noise bursts (music-like).
fn chords(n: usize, seed: u32) -> Vec<f32> {
let mut r = seed;
let notes = [220.0f32, 277.2, 329.6, 440.0, 349.2, 523.3, 392.0, 659.3];
(0..n)
.map(|i| {
let t = i as f32 / 48_000.0;
let chord = (t * 2.0) as usize;
let mut s = 0.0;
for k in 0..3 {
let f = notes[(chord * 3 + k * 2) % notes.len()];
for h in 1..6 {
s += (2.0 * std::f32::consts::PI * f * h as f32 * t).sin() * 0.08 / h as f32;
}
}
r = r.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
let env = (-(t * 2.0).fract() * 3.0).exp();
s * (0.5 + 0.5 * env) + 0.02 * ((r >> 8) as f32 / 8_388_608.0 - 1.0) * env
})
.collect()
}
/// ffmpeg's own Vorbis decoder and libvorbis read every stream exactly as long as the input,
/// with SNR floors about 6 dB (chords 4 dB) under what the encoder measured when written, and bit
/// rates near libvorbis's for the same quality.
/// A signal, and per quality the SNR floor and the bit-rate range (kbit/s).
type Case = (&'static str, Vec<Vec<f32>>, [(f32, f64, std::ops::Range<usize>); 5]);
#[test]
fn ffmpeg_decodes_every_quality() {
let Some(ff) = craft_media_testkit::ffmpeg_or_skip("vorbis oracle") else { return };
let n = 48_000 * 3;
let cases: [Case; 2] = [
(
"music",
vec![music(n, 1), music(n, 2).iter().map(|v| v * 0.7).collect()],
[(-1.0, 3.0, 15..90), (0.0, 6.5, 20..110), (3.0, 12.0, 60..180), (6.0, 18.5, 120..280), (10.0, 25.5, 180..400)],
),
(
"chords",
vec![chords(n, 1), chords(n, 2).iter().map(|v| v * 0.8).collect()],
[(-1.0, 4.5, 20..90), (0.0, 6.0, 25..110), (3.0, 10.0, 70..200), (6.0, 14.0, 130..300), (10.0, 19.0, 180..420)],
),
];
for (name, input, levels) in &cases {
for (q, floor, kbps) in levels {
for decoder in decoders(&ff) {
let Some((out, bytes)) = round_trip(input, 48_000, *q, decoder, &format!("{name}{q}")) else { return };
assert!(out.iter().all(|c| c.len() == n), "{name} q{q} {decoder}: length {}", out[0].len());
let snr = snr_db(&input[0][4096..], &out[0][4096..]);
assert!(snr >= *floor, "{name} q{q} {decoder}: {snr:.2} dB < {floor}");
let rate = bytes * 8 / 3 / 1000;
assert!(kbps.contains(&rate), "{name} q{q}: {rate} kbit/s outside {kbps:?}");
}
}
}
}
/// Mono, 44.1 kHz, 3.0, 5.1 and 6.1 streams decode too, with libvorbis as well (which reads each
/// residue partition from channel 0); a silent channel costs one bit per block.
#[test]
fn channel_counts_and_rates() {
let Some(ff) = craft_media_testkit::ffmpeg_or_skip("vorbis oracle") else { return };
let n = 44_100;
for (rate, ch) in [(44_100u32, 1usize), (22_050, 2), (48_000, 3), (48_000, 6), (48_000, 7)] {
let mut input: Vec<Vec<f32>> = (0..ch).map(|c| chords(n, c as u32 + 1).iter().map(|v| v * (1.0 - 0.1 * c as f32)).collect()).collect();
if ch == 6 {
input[3] = vec![0.0; n];
}
for decoder in decoders(&ff) {
let Some((mut out, _)) = round_trip(&input, rate, 5.0, decoder, &format!("ch{ch}_{rate}_{decoder}")) else { return };
if decoder == "vorbis" {
// ffmpeg's decoder gives WAV order (5.1: FL FR FC LFE BL BR); the stream is in Vorbis
// order (L C R Ls Rs LFE), which libvorbis passes through
let wav_to_vorbis: &[usize] = match ch {
3 => &[0, 2, 1],
6 => &[0, 2, 1, 4, 5, 3],
7 => &[0, 2, 1, 5, 6, 4, 3],
_ => &[0, 1],
};
if ch > 2 {
out = wav_to_vorbis.iter().map(|&i| out[i].clone()).collect();
}
}
assert_eq!(out.len(), ch);
for (c, (a, b)) in input.iter().zip(&out).enumerate() {
assert_eq!(b.len(), n, "{ch} ch {rate} Hz {decoder}: channel {c} length");
if a.iter().all(|&v| v == 0.0) {
assert!(b.iter().all(|v| v.abs() < 1e-6), "silent channel {c}");
} else {
let snr = snr_db(&a[4096..], &b[4096..]);
assert!(snr > 8.0, "{ch} ch {rate} Hz {decoder} channel {c}: {snr:.1} dB");
}
}
}
}
}
/// Every partition holds whole sample frames (libvorbis decodes each one from channel 0), splits
/// the interleaved residue evenly and fits every book's dimension.
#[test]
fn partitions_hold_whole_frames() {
for ch in 1..=8 {
let p = partition_size(ch);
assert_eq!(p % ch, 0, "{ch} channels");
assert_eq!((ch * BLOCK / 2) % p, 0, "{ch} channels");
assert_eq!(p % 4, 0, "{ch} channels");
}
}
+4
View File
@@ -0,0 +1,4 @@
//! Vorbis I (feature `vorbis-encode`): the pure-Rust [`encoder`]. Decoding Vorbis goes through
//! [`crate::decode`].
pub mod encoder;
+721
View File
@@ -0,0 +1,721 @@
//! Markers a WAV file carries, read from its RIFF chunks.
//!
//! Two encodings are read into separate lists for the caller to map and merge:
//! - **Cue points** (the standard): a `cue ` chunk with one point per marker, named by `labl` (or
//! `note`) sub-chunks of a `LIST` `adtl` chunk, and given a length by `ltxt`.
//! - **XMP** (Adobe's tools): an `_PMX` chunk holding an XMP packet whose `xmpDM:markers` list has
//! one entry per marker (`xmpDM:startTime`, `xmpDM:duration`, `xmpDM:name`), counted in frames
//! of `xmpDM:frameRate` (`f44100` for samples at 44.1 kHz), or with an explicit
//! FrameCount rate suffix (`15f24`, `15f30000s1001`). Durations with a distinct rate
//! are converted to the marker start rate without app-specific time quantization.
//!
//! RF64 files (WAVs over 4 GB) carry a `0xFFFFFFFF` size for a chunk too big for 32 bits and give its real size in a
//! `ds64` chunk; those sizes are resolved so the chunks after the audio are still found.
//!
//! The file is untrusted input: every read is bounds-checked, sizes use checked arithmetic, and
//! the number of markers, of `adtl` sub-chunks looked at and the size of the XMP packet are capped.
use std::collections::{HashMap, HashSet};
/// Marker coordinates before app-specific time quantization. Explicit XMP duration
/// rates are normalized to the start coordinate rate; bare counts retain the legacy
/// track/file-rate interpretation.
#[derive(Clone, Debug, PartialEq)]
pub struct Marker {
/// Start in frames at `rate`.
pub start: f64,
/// Duration in frames at `rate`.
pub duration: f64,
/// Frames per second; consumers decide how invalid or absent rates map to their timeline.
pub rate: f64,
/// Label text.
pub name: String,
}
/// Separate source lists: rounding, deduplication, ordering and labels belong to the caller.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Markers {
/// RIFF cue/adtl markers in file order.
pub cue: Vec<Marker>,
/// XMP markers in packet order.
pub xmp: Vec<Marker>,
/// A chunk-inventory or cue-label retention limit omitted metadata. Marker coordinates
/// remain available when only their label was omitted. Existing marker/XMP prefix limits
/// are separate and do not set this flag.
pub limited: bool,
}
/// Most markers read from one file.
pub const MAX_MARKERS: usize = 10_000;
/// Largest XMP packet read (bytes).
const MAX_XMP: usize = 4 << 20;
/// Most `adtl` sub-chunks (`labl`, `note`, `ltxt`) looked at in one file: a few per cue point is plenty.
const MAX_ADTL_RECORDS: usize = 4 * MAX_MARKERS;
/// Most entries read from an RF64 file's `ds64` size table.
const MAX_DS64_TABLE: usize = 1_024;
/// Maximum retained RIFF chunk descriptors (including empty chunks).
pub const MAX_CHUNKS: usize = 100_000;
/// Maximum UTF-8 bytes in one retained cue label.
pub const MAX_LABEL_BYTES: usize = 64 * 1024;
/// Aggregate cue label bytes, enforced separately for the name map and emitted markers.
pub const MAX_LABEL_TOTAL_BYTES: usize = 4 * 1024 * 1024;
fn u32_at(b: &[u8], at: usize) -> Option<u32> {
let s = b.get(at..at.checked_add(4)?)?;
Some(u32::from_le_bytes(s.try_into().ok()?))
}
fn u64_at(b: &[u8], at: usize) -> Option<u64> {
let s = b.get(at..at.checked_add(8)?)?;
Some(u64::from_le_bytes(s.try_into().ok()?))
}
/// The text of a NUL-terminated label (the rest of the chunk), lossily decoded.
fn label(b: &[u8]) -> Option<String> {
// Look only as far as one label can be retained; never copy an arbitrary chunk body.
let end = b.iter().take(MAX_LABEL_BYTES + 1).position(|&c| c == 0).unwrap_or(b.len());
if end > MAX_LABEL_BYTES {
return None;
}
let text = String::from_utf8_lossy(b.get(..end)?);
let text = text.trim();
(text.len() <= MAX_LABEL_BYTES).then(|| text.to_string())
}
/// Whether `bytes` start a RIFF/WAVE file.
pub fn is_wav(bytes: &[u8]) -> bool {
matches!(bytes.get(0..4), Some(b"RIFF" | b"RF64")) && bytes.get(8..12) == Some(b"WAVE")
}
/// The sizes an RF64 file's `ds64` chunk gives for chunks too big for the 32-bit size field.
struct Ds64 {
/// The `data` chunk's size.
data: u64,
/// Other chunks: `(id, size)`.
table: Vec<([u8; 4], u64)>,
}
impl Ds64 {
/// The real size of chunk `id`, when the file says.
fn size_of(&self, id: &[u8; 4]) -> Option<u64> {
if id == b"data" { Some(self.data) } else { self.table.iter().find(|(t, _)| t == id).map(|(_, size)| *size) }
}
}
/// The `ds64` chunk of an RF64 file (`RF64`, size, `WAVE`, then `ds64`); `None` for any other file or one whose
/// `ds64` doesn't fit.
fn ds64(bytes: &[u8]) -> Option<Ds64> {
if bytes.get(0..4) != Some(b"RF64") || bytes.get(12..16) != Some(b"ds64") {
return None;
}
let size = usize::try_from(u32_at(bytes, 16)?).ok()?;
let body = bytes.get(20..20usize.checked_add(size)?)?;
// riff size (8), data size (8), sample count (8), table length (4), then `(id, size)` entries of 12 bytes
let data = u64_at(body, 8)?;
let entries = usize::try_from(u32_at(body, 24)?).ok()?;
let mut table = Vec::new();
for i in 0..entries.min(MAX_DS64_TABLE) {
let at = 28usize.checked_add(i.checked_mul(12)?)?;
let id = <[u8; 4]>::try_from(body.get(at..at.checked_add(4)?)?).ok()?;
table.push((id, u64_at(body, at + 4)?));
}
Some(Ds64 { data, table })
}
/// The chunks of a WAVE file as `(id, body)`, stopping at the first one that doesn't fit.
fn chunks<'a>(bytes: &'a [u8], limited: &mut bool) -> Vec<([u8; 4], &'a [u8])> {
let big = ds64(bytes);
let mut out = Vec::new();
let mut at = 12usize;
while let Some(head) = bytes.get(at..at.saturating_add(8)) {
if out.len() == MAX_CHUNKS {
*limited = true;
break;
}
let (Ok(id), Some(field)) = (<[u8; 4]>::try_from(&head[..4]), u32_at(head, 4)) else { break };
// In an RF64 file a size field of 0xFFFFFFFF stands for the size `ds64` gives.
let size = match &big {
Some(d) if field == u32::MAX => d.size_of(&id).unwrap_or(u64::from(field)),
_ => u64::from(field),
};
let start = at.saturating_add(8);
let Some(end) = usize::try_from(size).ok().and_then(|n| start.checked_add(n)) else { break };
let Some(body) = bytes.get(start..end) else { break };
out.push((id, body));
// Chunks are padded to an even size.
at = end.saturating_add(end & 1);
}
out
}
/// Read bounded cue/adtl and XMP metadata without interpreting application timeline policy.
pub fn read(bytes: &[u8]) -> Markers {
if !is_wav(bytes) {
return Markers::default();
}
let mut limited = false;
let chunks = chunks(bytes, &mut limited);
let rate = chunks.iter().find(|(id, _)| id == b"fmt ").and_then(|(_, b)| u32_at(b, 4)).map_or(0.0, f64::from);
let cue = cue_markers(&chunks, rate, &mut limited);
let xmp = chunks.iter().find(|(id, _)| id == b"_PMX").map_or_else(Vec::new, |(_, xmp)| xmp_markers(xmp, rate));
Markers { cue, xmp, limited }
}
/// Cue points named and sized by the `adtl` list.
fn cue_markers(chunks: &[([u8; 4], &[u8])], rate: f64, limited: &mut bool) -> Vec<Marker> {
let Some((_, cue)) = chunks.iter().find(|(id, _)| id == b"cue ") else { return Vec::new() };
let count = (u32_at(cue, 0).unwrap_or(0) as usize).min(MAX_MARKERS);
// The cue points first: `(id, offset in samples)`.
let mut points = Vec::new();
for i in 0..count {
let Some(point) = cue.get(4usize.saturating_add(i.saturating_mul(24))..) else { break };
let (Some(id), Some(offset)) = (u32_at(point, 0), u32_at(point, 20)) else { break };
points.push((id, offset));
}
// Only the names and lengths of those ids are kept, so a hostile `adtl` list cannot grow them past the cue count,
// and each record is a lookup, not a scan.
let wanted: HashSet<u32> = points.iter().map(|(id, _)| *id).collect();
let mut names: HashMap<u32, String> = HashMap::new();
let mut lengths: HashMap<u32, u32> = HashMap::new();
let mut name_bytes = 0usize;
let mut records = 0usize;
'lists: for (_, list) in chunks.iter().filter(|(id, b)| id == b"LIST" && b.get(0..4) == Some(b"adtl")) {
let mut at = 4usize;
while let Some(head) = list.get(at..at.saturating_add(8)) {
let (Ok(id), Some(size)) = (<[u8; 4]>::try_from(&head[..4]), u32_at(head, 4)) else { break };
let start = at.saturating_add(8);
let Some(end) = start.checked_add(size as usize) else { break };
let Some(body) = list.get(start..end) else { break };
records += 1;
if records > MAX_ADTL_RECORDS {
break 'lists;
}
if let Some(cue_id) = u32_at(body, 0).filter(|c| wanted.contains(c)) {
match &id {
// A `labl` is the name; a `note` only when there is none.
b"labl" | b"note" if id == *b"labl" || !names.contains_key(&cue_id) => {
let without_old = name_bytes.saturating_sub(names.get(&cue_id).map_or(0, String::len));
let text = label(body.get(4..).unwrap_or_default())
.filter(|text| text.len() <= MAX_LABEL_TOTAL_BYTES.saturating_sub(without_old))
.unwrap_or_else(|| {
*limited = true;
String::new()
});
name_bytes = without_old + text.len();
names.insert(cue_id, text);
}
// The first `ltxt` of a cue point gives its length.
b"ltxt" => {
lengths.entry(cue_id).or_insert_with(|| u32_at(body, 4).unwrap_or(0));
}
_ => {}
}
}
at = end.saturating_add(end & 1);
}
}
let mut emitted_bytes = 0usize;
points
.into_iter()
.map(|(id, offset)| {
let comment = match names.get(&id) {
Some(text) if text.len() <= MAX_LABEL_TOTAL_BYTES.saturating_sub(emitted_bytes) => {
emitted_bytes += text.len();
text.clone()
}
Some(_) => {
*limited = true;
String::new()
}
None => String::new(),
};
let length = lengths.get(&id).copied().unwrap_or(0);
Marker { start: f64::from(offset), duration: f64::from(length), rate, name: comment }
})
.collect()
}
/// The text of `name` in an XMP entry, as an attribute (`name="v"`) or an element
/// (`<name>v</name>`).
fn xmp_value(entry: &str, name: &str) -> Option<String> {
// Each entry starts just after `<rdf:li`. Scan only tag attributes, skipping
// quoted values so a label containing an attribute-like string cannot spoof it.
let bytes = entry.as_bytes();
let mut at = 0;
let mut in_tag = true;
while at < bytes.len() {
match bytes[at] {
b'<' => in_tag = true,
b'>' => in_tag = false,
b'\'' | b'"' if in_tag => {
let quote = bytes[at];
at += 1;
while at < bytes.len() && bytes[at] != quote {
at += 1;
}
}
_ if in_tag && (at == 0 || xml_space(bytes[at - 1])) && bytes[at..].starts_with(name.as_bytes()) => {
let mut value = at + name.len();
while value < bytes.len() && xml_space(bytes[value]) {
value += 1;
}
if bytes.get(value) == Some(&b'=') {
value += 1;
while value < bytes.len() && xml_space(bytes[value]) {
value += 1;
}
if let Some(&quote @ (b'\'' | b'"')) = bytes.get(value) {
let start = value + 1;
let end = bytes.get(start..)?.iter().position(|&b| b == quote)? + start;
return Some(unescape(entry.get(start..end)?));
}
}
}
_ => {}
}
at += 1;
}
let open = format!("<{name}>");
let i = entry.find(&open)?;
let rest = entry.get(i + open.len()..)?;
Some(unescape(rest.get(..rest.find('<')?)?))
}
fn xml_space(b: u8) -> bool {
matches!(b, b' ' | b'\t' | b'\r' | b'\n')
}
fn unescape(s: &str) -> String {
let mut out = String::with_capacity(s.len());
let mut rest = s;
while let Some(i) = rest.find('&') {
out.push_str(rest.get(..i).unwrap_or_default());
let tail = rest.get(i..).unwrap_or_default();
let Some(semi) = tail.as_bytes().iter().take(11).position(|b| *b == b';') else {
out.push('&');
rest = tail.get(1..).unwrap_or_default();
continue;
};
let ent = tail.get(1..semi).unwrap_or_default();
match ent {
"amp" => out.push('&'),
"lt" => out.push('<'),
"gt" => out.push('>'),
"quot" => out.push('"'),
"apos" => out.push('\''),
_ => {
let code = ent
.strip_prefix("#x")
.and_then(|h| u32::from_str_radix(h, 16).ok())
.or_else(|| ent.strip_prefix('#').and_then(|d| d.parse().ok()));
match code.and_then(char::from_u32) {
Some(c) => out.push(c),
None => out.push_str(tail.get(..=semi).unwrap_or_default()),
}
}
}
rest = tail.get(semi + 1..).unwrap_or_default();
}
out.push_str(rest);
out.trim().to_string()
}
/// A frame rate as XMP writes it: `f44100`, or `f30000s1001` (rate over scale).
fn xmp_rate(text: &str) -> Option<f64> {
let t = text.trim().strip_prefix('f')?;
let (num, den) = t.split_once('s').unwrap_or((t, "1"));
let (n, d): (f64, f64) = (num.parse().ok()?, den.parse().ok()?);
(n.is_finite() && d.is_finite() && n > 0.0 && d > 0.0 && (n / d).is_finite() && n / d > 0.0).then_some(n / d)
}
/// Adobe XMP FrameCount: a count optionally followed by `fRATE[sSCALE]`.
/// Bare counts retain the caller's legacy track/file-rate interpretation.
fn xmp_count(text: &str, default_rate: f64) -> Option<(f64, f64)> {
let text = text.trim();
let (count, rate) = match text.find('f') {
Some(at) => (text.get(..at)?, xmp_rate(text.get(at..)?)?),
None => (text, default_rate),
};
let count: f64 = count.parse().ok()?;
(count.is_finite() && rate.is_finite() && rate > 0.0).then_some((count, rate))
}
/// The markers of an XMP packet's `xmpDM:markers` entries.
fn xmp_markers(packet: &[u8], file_rate: f64) -> Vec<Marker> {
let text = String::from_utf8_lossy(packet.get(..packet.len().min(MAX_XMP)).unwrap_or_default());
let mut out = Vec::new();
// The frame rate belongs to the track an entry follows.
let mut rate = file_rate;
for entry in text.split("<rdf:li").skip(1) {
if let Some(r) = xmp_value(entry, "xmpDM:frameRate").as_deref().and_then(xmp_rate) {
rate = r;
}
let Some((start, marker_rate)) = xmp_value(entry, "xmpDM:startTime").and_then(|v| xmp_count(&v, rate)) else { continue };
let length = xmp_value(entry, "xmpDM:duration")
.and_then(|v| xmp_count(&v, rate))
.map(|(count, duration_rate)| if duration_rate == marker_rate { count } else { count / duration_rate * marker_rate })
.unwrap_or(0.0);
if !length.is_finite() {
continue;
}
let comment = xmp_value(entry, "xmpDM:name").unwrap_or_default();
out.push(Marker { start, duration: length, rate: marker_rate, name: comment });
if out.len() >= MAX_MARKERS {
break;
}
}
out
}
#[cfg(test)]
mod tests {
use super::*;
struct TimedMarker {
time: f64,
duration: f64,
comment: String,
}
fn read(bytes: &[u8]) -> Vec<TimedMarker> {
let metadata = super::read(bytes);
let time = |frames: f64, rate: f64| if rate > 0.0 && frames.is_finite() { (frames / rate).max(0.0) } else { 0.0 };
let map = |m: Marker| TimedMarker { time: time(m.start, m.rate), duration: time(m.duration, m.rate), comment: m.name };
let mut out: Vec<_> = metadata.cue.into_iter().map(map).collect();
let mut seen: HashSet<_> = out.iter().map(|m| (m.comment.clone(), m.time.to_bits())).collect();
for m in metadata.xmp.into_iter().map(map) {
if seen.insert((m.comment.clone(), m.time.to_bits())) {
out.push(m);
}
}
out.truncate(MAX_MARKERS);
out.sort_by(|a, b| a.time.total_cmp(&b.time));
out
}
fn chunk(id: &[u8; 4], body: &[u8]) -> Vec<u8> {
let mut v = id.to_vec();
v.extend((body.len() as u32).to_le_bytes());
v.extend(body);
if body.len() % 2 == 1 {
v.push(0);
}
v
}
fn fmt(rate: u32) -> Vec<u8> {
let mut b = Vec::new();
b.extend(1u16.to_le_bytes()); // PCM
b.extend(1u16.to_le_bytes()); // mono
b.extend(rate.to_le_bytes());
b.extend((rate * 2).to_le_bytes());
b.extend(2u16.to_le_bytes());
b.extend(16u16.to_le_bytes());
chunk(b"fmt ", &b)
}
fn wav(chunks: &[Vec<u8>]) -> Vec<u8> {
let body: Vec<u8> = chunks.iter().flatten().copied().collect();
let mut v = b"RIFF".to_vec();
v.extend((body.len() as u32 + 4).to_le_bytes());
v.extend(b"WAVE");
v.extend(body);
v
}
fn cue(points: &[(u32, u32)]) -> Vec<u8> {
let mut b = (points.len() as u32).to_le_bytes().to_vec();
for (id, offset) in points {
b.extend(id.to_le_bytes());
b.extend(0u32.to_le_bytes());
b.extend(b"data");
b.extend(0u32.to_le_bytes());
b.extend(0u32.to_le_bytes());
b.extend(offset.to_le_bytes());
}
chunk(b"cue ", &b)
}
fn labl(id: &[u8; 4], cue_id: u32, text: &str) -> Vec<u8> {
let mut b = cue_id.to_le_bytes().to_vec();
b.extend(text.as_bytes());
b.push(0);
chunk(id, &b)
}
fn adtl(subs: &[Vec<u8>]) -> Vec<u8> {
let mut b = b"adtl".to_vec();
b.extend(subs.iter().flatten());
chunk(b"LIST", &b)
}
#[test]
fn cue_points_are_named_by_the_adtl_list_and_timed_in_samples() {
let file = wav(&[
fmt(44100),
chunk(b"data", &[0; 8]),
cue(&[(2, 88200), (1, 22050)]),
adtl(&[labl(b"labl", 1, "SEQ01_Prologue"), labl(b"labl", 2, "SEQ02_Vallee_P1_Agriculture")]),
]);
let m = read(&file);
assert_eq!(m.len(), 2);
assert_eq!((m[0].comment.as_str(), m[0].time), ("SEQ01_Prologue", 0.5));
assert_eq!((m[1].comment.as_str(), m[1].time), ("SEQ02_Vallee_P1_Agriculture", 2.0));
}
#[test]
fn a_note_names_a_cue_only_when_it_has_no_label_and_ltxt_gives_a_length() {
let mut ltxt = 1u32.to_le_bytes().to_vec();
ltxt.extend(44100u32.to_le_bytes());
ltxt.extend([0; 16]);
let file = wav(&[
fmt(44100),
cue(&[(1, 0), (2, 44100)]),
adtl(&[labl(b"note", 1, "from note"), chunk(b"ltxt", &ltxt), labl(b"labl", 2, "named"), labl(b"note", 2, "ignored")]),
]);
let m = read(&file);
assert_eq!((m[0].comment.as_str(), m[0].duration), ("from note", 1.0));
assert_eq!(m[1].comment, "named");
}
const XMP_ELEMENTS: &str = r#"<x:xmpmeta><rdf:RDF><rdf:Description><xmpDM:Tracks><rdf:Bag><rdf:li rdf:parseType="Resource"><xmpDM:trackName>Markers</xmpDM:trackName><xmpDM:trackType>Cue</xmpDM:trackType><xmpDM:frameRate>f44100</xmpDM:frameRate><xmpDM:markers><rdf:Seq><rdf:li rdf:parseType="Resource"><xmpDM:startTime>44100</xmpDM:startTime><xmpDM:duration>0</xmpDM:duration><xmpDM:name>One &amp; Two</xmpDM:name></rdf:li><rdf:li rdf:parseType="Resource"><xmpDM:startTime>132300</xmpDM:startTime><xmpDM:duration>22050</xmpDM:duration><xmpDM:name>Three</xmpDM:name></rdf:li></rdf:Seq></xmpDM:markers></rdf:li></rdf:Bag></xmpDM:Tracks></rdf:Description></rdf:RDF></x:xmpmeta>"#;
#[test]
fn xmp_markers_are_read_as_elements_in_frames_of_the_track_rate() {
let file = wav(&[fmt(48000), chunk(b"_PMX", XMP_ELEMENTS.as_bytes())]);
let m = read(&file);
assert_eq!(m.len(), 2);
// 44100 frames at f44100 is one second, whatever the file's own rate.
assert_eq!((m[0].comment.as_str(), m[0].time), ("One & Two", 1.0));
assert_eq!((m[1].comment.as_str(), m[1].time, m[1].duration), ("Three", 3.0, 0.5));
}
#[test]
fn xmp_markers_are_read_as_attributes_and_use_the_file_rate_without_a_track_rate() {
let xmp = r#"<rdf:Seq><rdf:li xmpDM:startTime="24000" xmpDM:duration="0" xmpDM:name="Attr &#233;"/></rdf:Seq>"#;
let m = read(&wav(&[fmt(48000), chunk(b"_PMX", xmp.as_bytes())]));
assert_eq!((m[0].comment.as_str(), m[0].time), ("Attr é", 0.5));
}
#[test]
fn a_marker_in_both_encodings_is_listed_once() {
let xmp = r#"<rdf:li xmpDM:startTime="44100" xmpDM:name="Same"/><rdf:li xmpDM:startTime="88200" xmpDM:name="Only XMP"/>"#;
let file = wav(&[fmt(44100), cue(&[(1, 44100)]), adtl(&[labl(b"labl", 1, "Same")]), chunk(b"_PMX", xmp.as_bytes())]);
let names: Vec<String> = read(&file).into_iter().map(|m| m.comment).collect();
assert_eq!(names, ["Same", "Only XMP"]);
}
#[test]
fn damaged_or_hostile_files_read_as_far_as_they_go_without_panicking() {
assert!(read(b"").is_empty());
assert!(read(b"RIFF").is_empty());
assert!(read(b"not a wav file at all").is_empty());
let good = wav(&[fmt(44100), cue(&[(1, 44100)]), adtl(&[labl(b"labl", 1, "Kept")])]);
// Every truncation is safe.
for n in 0..good.len() {
let _ = read(&good[..n]);
}
// A cue count far beyond the chunk, and chunk sizes past the end of the file.
let mut huge = 0xFFFF_FFFFu32.to_le_bytes().to_vec();
huge.extend([0; 24]);
let m = read(&wav(&[fmt(44100), chunk(b"cue ", &huge)]));
assert!(m.len() <= 1);
let mut lying = good.clone();
lying.extend(b"LIST\xff\xff\xff\xffadtl");
assert_eq!(read(&lying).len(), 1);
// No sample rate: times are zero, not a division by zero.
let m = read(&wav(&[cue(&[(1, 44100)])]));
assert_eq!(m[0].time, 0.0);
}
/// A chunk whose size field says `field` (an RF64 file's `0xFFFFFFFF`) while its body is `body`.
fn chunk_with_size_field(id: &[u8; 4], field: u32, body: &[u8]) -> Vec<u8> {
let mut v = id.to_vec();
v.extend(field.to_le_bytes());
v.extend(body);
if body.len() % 2 == 1 {
v.push(0);
}
v
}
/// An RF64 `ds64` chunk: the `data` chunk's size and a table of other chunks' sizes.
fn ds64_chunk(data_size: u64, table: &[([u8; 4], u64)]) -> Vec<u8> {
let mut b = 0u64.to_le_bytes().to_vec(); // riff size (not used)
b.extend(data_size.to_le_bytes());
b.extend(0u64.to_le_bytes()); // sample count
b.extend((table.len() as u32).to_le_bytes());
for (id, size) in table {
b.extend(id);
b.extend(size.to_le_bytes());
}
chunk(b"ds64", &b)
}
fn rf64(chunks: &[Vec<u8>]) -> Vec<u8> {
let body: Vec<u8> = chunks.iter().flatten().copied().collect();
let mut v = b"RF64".to_vec();
v.extend(u32::MAX.to_le_bytes());
v.extend(b"WAVE");
v.extend(body);
v
}
#[test]
fn rf64_markers_after_a_data_chunk_of_sentinel_size_are_read() {
let audio = [0u8; 8];
let file = rf64(&[
ds64_chunk(audio.len() as u64, &[]),
fmt(44100),
chunk_with_size_field(b"data", u32::MAX, &audio),
cue(&[(1, 44100)]),
adtl(&[labl(b"labl", 1, "After the audio")]),
]);
let m = read(&file);
assert_eq!(m.len(), 1);
assert_eq!((m[0].comment.as_str(), m[0].time), ("After the audio", 1.0));
}
#[test]
fn rf64_sizes_of_other_chunks_come_from_the_ds64_table() {
let junk = [7u8; 6];
let tail = || [cue(&[(1, 8000)]), adtl(&[labl(b"labl", 1, "Found")])].concat();
let with_entry = rf64(&[ds64_chunk(0, &[(*b"junk", junk.len() as u64)]), fmt(8000), chunk_with_size_field(b"junk", u32::MAX, &junk), tail()]);
assert_eq!(read(&with_entry)[0].comment, "Found");
// Without the table entry the sentinel is all there is, and what follows is not reached.
let without = rf64(&[ds64_chunk(0, &[]), fmt(8000), chunk_with_size_field(b"junk", u32::MAX, &junk), tail()]);
assert!(read(&without).is_empty());
}
#[test]
fn hostile_rf64_size_tables_read_as_far_as_they_go_without_panicking() {
// sizes that overflow when added to an offset
for data in [u64::MAX, u64::MAX - 7, 1 << 63] {
let file =
rf64(&[ds64_chunk(data, &[(*b"junk", u64::MAX)]), fmt(8000), chunk_with_size_field(b"data", u32::MAX, &[0; 4]), cue(&[(1, 0)])]);
assert!(read(&file).is_empty());
}
// a table that claims far more entries than its chunk holds
let mut liar = ds64_chunk(0, &[]);
liar[8 + 24..8 + 28].copy_from_slice(&u32::MAX.to_le_bytes());
let _ = read(&rf64(&[liar, fmt(8000), cue(&[(1, 0)])]));
// every truncation of a good RF64 file is safe
let good = rf64(&[
ds64_chunk(4, &[]),
fmt(44100),
chunk_with_size_field(b"data", u32::MAX, &[0; 4]),
cue(&[(1, 44100)]),
adtl(&[labl(b"labl", 1, "Kept")]),
]);
assert_eq!(read(&good).len(), 1);
for n in 0..good.len() {
let _ = read(&good[..n]);
}
}
#[test]
fn a_huge_adtl_list_is_read_in_linear_time_and_only_for_the_cue_points_that_exist() {
// Records for ids that have no cue point are skipped, not stored, and the number looked at is capped.
let junk = |n: u32| (1000..1000 + n).map(|id| labl(b"labl", id, "n")).collect::<Vec<_>>();
let started = std::time::Instant::now();
// the real label comes first: read
let mut subs = vec![labl(b"labl", 1, "Real")];
subs.extend(junk(100_000));
let m = read(&wav(&[fmt(44100), cue(&[(1, 44100)]), adtl(&subs)]));
assert_eq!(m[0].comment, "Real");
// it comes after more records than are looked at: not read, and the marker is still there
let mut subs = junk(MAX_ADTL_RECORDS as u32 + 10);
subs.push(labl(b"labl", 1, "Too late"));
let m = read(&wav(&[fmt(44100), cue(&[(1, 44100)]), adtl(&subs)]));
assert_eq!((m.len(), m[0].comment.as_str()), (1, ""));
assert!(started.elapsed() < std::time::Duration::from_secs(5), "took {:?}", started.elapsed());
}
#[test]
fn metadata_keeps_original_coordinates_and_separate_sources() {
let xmp = br#"<rdf:li xmpDM:startTime="1" xmpDM:duration="2" xmpDM:name="Same"/>"#;
let file = wav(&[fmt(44100), cue(&[(1, 1)]), adtl(&[labl(b"labl", 1, "Same")]), chunk(b"_PMX", xmp)]);
let data = super::read(&file);
assert_eq!(data.cue[0].start, 1.0);
assert_eq!(data.cue[0].rate, 44100.0);
assert_eq!(data.xmp[0].start, 1.0);
assert_eq!(data.xmp[0].duration, 2.0);
assert_eq!(data.cue.len(), 1);
assert_eq!(data.xmp.len(), 1);
}
#[test]
fn repeated_unterminated_entities_preserve_text_with_bounded_lookahead() {
let text = "&".repeat(100_000);
assert_eq!(unescape(&text), text);
assert_eq!(unescape("&#0000065; &#00000065; &amp; &unknown;"), "A A & &unknown;");
}
#[test]
fn repeated_cue_ids_cannot_multiply_label_storage() {
let text = "x".repeat(MAX_LABEL_BYTES);
let points: Vec<_> = (0..MAX_MARKERS).map(|i| (1, i as u32)).collect();
let file = wav(&[fmt(44100), cue(&points), adtl(&[labl(b"labl", 1, &text)])]);
let metadata = super::read(&file);
assert_eq!(metadata.cue.len(), MAX_MARKERS);
assert_eq!(metadata.cue.iter().map(|m| m.name.len()).sum::<usize>(), MAX_LABEL_TOTAL_BYTES);
assert!(metadata.limited);
assert_eq!(metadata.cue[0].name, text);
assert!(metadata.cue[MAX_MARKERS - 1].name.is_empty());
assert_eq!(metadata.cue[MAX_MARKERS - 1].start, (MAX_MARKERS - 1) as f64);
}
#[test]
fn cue_name_map_and_single_label_are_bounded() {
let count = MAX_LABEL_TOTAL_BYTES / MAX_LABEL_BYTES + 2;
let text = "x".repeat(MAX_LABEL_BYTES);
let points: Vec<_> = (0..count as u32).map(|i| (i, i)).collect();
let labels: Vec<_> = (0..count as u32).map(|i| labl(b"labl", i, &text)).collect();
let metadata = super::read(&wav(&[fmt(44100), cue(&points), adtl(&labels)]));
assert!(metadata.limited);
assert_eq!(metadata.cue.iter().map(|m| m.name.len()).sum::<usize>(), MAX_LABEL_TOTAL_BYTES);
let oversized = "x".repeat(MAX_LABEL_BYTES + 1);
let metadata = super::read(&wav(&[fmt(44100), cue(&[(1, 3)]), adtl(&[labl(b"labl", 1, &oversized)])]));
assert!(metadata.limited);
assert_eq!(metadata.cue[0].start, 3.0);
assert!(metadata.cue[0].name.is_empty());
}
#[test]
fn empty_chunk_inventory_is_bounded() {
let empty = chunk(b"junk", &[]);
let many = empty.repeat(MAX_CHUNKS + 1);
let metadata = super::read(&wav(&[many, fmt(44100), cue(&[(1, 1)])]));
assert!(metadata.limited);
assert!(metadata.cue.is_empty());
}
#[test]
fn entity_lookahead_keeps_previous_semicolon_boundary() {
assert_eq!(unescape("&#00000065;"), "A");
assert_eq!(unescape("&#000000065;"), "&#000000065;");
}
#[test]
fn xmp_quotes_spacing_and_attribute_boundaries() {
let packet = br#"<rdf:li xmpDM:startTime = '24000' xmpDM:duration =
'12000' xmpDM:name='single &amp; quoted'/>"#;
let markers = xmp_markers(packet, 48000.0);
assert_eq!(markers.len(), 1);
assert_eq!((markers[0].start, markers[0].duration, markers[0].rate), (24000.0, 12000.0, 48000.0));
assert_eq!(markers[0].name, "single & quoted");
let spoof = r#" label=" xmpDM:startTime='7'" otherxmpDM:startTime='8' xmpDM:startTime = '9'/>"#;
assert_eq!(xmp_value(spoof, "xmpDM:startTime").as_deref(), Some("9"));
assert!(xmp_value(" xmpDM:startTime='unterminated", "xmpDM:startTime").is_none());
}
#[test]
fn xmp_frame_counts_preserve_explicit_and_mixed_rates() {
let packet = br#"<rdf:li xmpDM:frameRate='f48000'><rdf:li xmpDM:startTime='15f24' xmpDM:duration='15f30000s1001'/><rdf:li xmpDM:startTime='48000' xmpDM:duration='12f24'/><rdf:li xmpDM:startTime='15f24' xmpDM:duration='24000'/></rdf:li>"#;
let markers = xmp_markers(packet, 44100.0);
assert_eq!(markers.len(), 3);
assert_eq!((markers[0].start, markers[0].rate), (15.0, 24.0));
assert!((markers[0].duration / markers[0].rate - 0.5005).abs() < 1e-12);
assert_eq!((markers[1].start, markers[1].duration, markers[1].rate), (48000.0, 24000.0, 48000.0));
assert_eq!((markers[2].start, markers[2].duration, markers[2].rate), (15.0, 12.0, 24.0));
for invalid in ["15f0", "15f24s0", "15fNaN", "15finf", "NaN", "1e999", "15f24junk"] {
assert!(xmp_count(invalid, 48000.0).is_none(), "{invalid}");
}
}
}
+223
View File
@@ -0,0 +1,223 @@
//! Range-backed PCM WAVE reader and canonical 16-bit writer.
//!
//! Reads chunk headers and only the requested sample range; it never loads a whole file.
use crate::{AudioError, Result};
use craft_media::ByteSource;
/// Whether a prefix identifies a RIFF or RF64 WAVE file.
pub fn sniff(b: &[u8]) -> bool {
b.len() >= 12 && (&b[0..4] == b"RIFF" || &b[0..4] == b"RF64") && &b[8..12] == b"WAVE"
}
const MAX_CHUNKS: usize = 1 << 16;
const IXML_MAX: u64 = 1 << 20;
/// Maximum sample data returned by a single range read.
pub const MAX_RANGE_BYTES: u64 = 4 << 20;
fn le16(b: &[u8], o: usize) -> u16 {
b.get(o..o.saturating_add(2)).and_then(|s| s.try_into().ok()).map_or(0, u16::from_le_bytes)
}
fn le32(b: &[u8], o: usize) -> u32 {
b.get(o..o.saturating_add(4)).and_then(|s| s.try_into().ok()).map_or(0, u32::from_le_bytes)
}
fn read_range(source: &impl ByteSource, off: u64, len: usize) -> Result<Vec<u8>> {
let mut bytes = vec![0; len];
source.read_at(off, &mut bytes)?;
Ok(bytes)
}
/// A PCM WAVE file held by an arbitrary random-access source.
pub struct WavRange<S> {
source: S,
/// Number of complete sample frames.
pub frames: u64,
/// Channel count.
pub channels: u16,
/// Sample rate in Hz.
pub rate: u32,
/// Container bits per sample.
pub bits: u16,
/// Whether samples are floating point.
pub float: bool,
/// BWF time reference in samples, from bext or iXML.
pub time_reference: Option<u64>,
data_off: u64,
}
impl<S: ByteSource> WavRange<S> {
/// Open with caller-selected bounds on channel count and sample rate.
pub fn open(source: S, max_channels: u32, max_rate: u32) -> Result<Self> {
let len = source.len();
let mut pos: u64 = 12;
let mut fmt = None;
let mut data = None;
let mut bext_tr = None;
let mut ixml_tr = None;
let mut ds64_data = None;
for _ in 0..MAX_CHUNKS {
let Some(body) = pos.checked_add(8).filter(|&b| b <= len) else { break };
let mut hdr = [0u8; 8];
source.read_at(pos, &mut hdr)?;
let id = &hdr[0..4];
let mut clen = u64::from(le32(&hdr, 4));
let rest = len - body;
if id == b"data" {
if clen == 0xFFFF_FFFF {
clen = ds64_data.unwrap_or(rest);
}
clen = clen.min(rest);
}
if clen > rest {
break;
}
match id {
b"fmt " if clen >= 16 => {
let b = read_range(&source, body, clen.min(40) as usize)?;
let mut tag = le16(&b, 0);
if tag == 0xFFFE && clen >= 40 {
tag = le16(&b, 24);
}
fmt = Some((tag, le16(&b, 2), le32(&b, 4), le16(&b, 14)));
}
b"ds64" if clen >= 16 => {
let b = read_range(&source, body + 8, 8)?;
ds64_data = Some(u64::from(le32(&b, 0)) | u64::from(le32(&b, 4)) << 32);
}
b"data" => data = Some((body, clen)),
b"bext" if clen >= 346 => {
let b = read_range(&source, body + 338, 8)?;
bext_tr = Some(u64::from(le32(&b, 0)) | u64::from(le32(&b, 4)) << 32);
}
b"iXML" => {
let b = read_range(&source, body, clen.min(IXML_MAX) as usize)?;
ixml_tr = ixml_time_reference(&b);
}
_ => {}
}
pos = body.saturating_add(clen).saturating_add(clen & 1);
}
let (tag, channels, rate, bits) = fmt.ok_or_else(|| AudioError::Malformed("missing fmt chunk".into()))?;
let (data_off, dlen) = data.ok_or_else(|| AudioError::Malformed("missing data chunk".into()))?;
let float = tag == 3;
if !(tag == 1 || float)
|| channels == 0
|| rate == 0
|| u32::from(channels) > max_channels
|| rate > max_rate
|| !matches!(bits, 8 | 16 | 24 | 32 | 64)
{
return Err(AudioError::Unsupported(format!("WAV format tag {tag}, {bits} bits")));
}
let frames = dlen / (u64::from(channels) * u64::from(bits / 8));
Ok(Self { source, frames, channels, rate, bits, float, time_reference: bext_tr.or(ixml_tr), data_off })
}
/// Bytes in one whole frame.
pub fn frame_bytes(&self) -> usize {
usize::from(self.channels) * usize::from(self.bits / 8)
}
/// Read the inclusive range of frames, capped to prevent unbounded allocation.
pub fn read_frames(&self, first: u64, last: u64) -> Result<Vec<u8>> {
if first > last || last >= self.frames {
return Err(AudioError::Malformed("WAV frame range outside data".into()));
}
let n = (last - first + 1).saturating_mul(self.frame_bytes() as u64);
if n > MAX_RANGE_BYTES {
return Err(AudioError::TooLarge("WAV frame range".into()));
}
let off = self.data_off.saturating_add(first.saturating_mul(self.frame_bytes() as u64));
read_range(&self.source, off, n as usize)
}
/// Decode a channel from a buffer returned by `read_frames`.
pub fn sample(&self, block: &[u8], frame: usize, ch: usize) -> f32 {
if ch >= usize::from(self.channels) {
return 0.0;
}
let bps = usize::from(self.bits / 8);
let Some(o) = frame.checked_mul(usize::from(self.channels)).and_then(|v| v.checked_add(ch)).and_then(|v| v.checked_mul(bps)) else {
return 0.0;
};
let Some(b) = block.get(o..o.saturating_add(bps)) else { return 0.0 };
match (self.bits, self.float, b) {
(8, _, &[a]) => (a as f32 - 128.0) / 128.0,
(16, _, &[a, b]) => i16::from_le_bytes([a, b]) as f32 / 32768.0,
(24, _, &[a, b, c]) => (i32::from_le_bytes([0, a, b, c]) >> 8) as f32 / 8_388_608.0,
(32, false, &[a, b, c, d]) => i32::from_le_bytes([a, b, c, d]) as f32 / 2_147_483_648.0,
(32, true, &[a, b, c, d]) => f32::from_le_bytes([a, b, c, d]),
(64, true, b) => f64::from_le_bytes(b.try_into().unwrap_or([0; 8])) as f32,
_ => 0.0,
}
}
}
fn ixml_time_reference(x: &[u8]) -> Option<u64> {
let text = String::from_utf8_lossy(x);
let field = |tag: &str| -> Option<u64> {
let open = format!("<{tag}>");
let a = text.find(&open)? + open.len();
let b = a + text[a..].find('<')?;
text[a..b].trim().parse().ok()
};
let low = field("BWF_TIME_REFERENCE_LOW")?;
Some(low | field("BWF_TIME_REFERENCE_HIGH").unwrap_or(0) << 32)
}
/// Write interleaved samples as 16-bit PCM WAVE, using symmetric 32767 scaling.
#[cfg(feature = "pcm-encode")]
pub fn write_wav16(samples: &[f32], channels: u16, rate: u32) -> Vec<u8> {
let data_len = samples.len().saturating_mul(2);
let mut v = crate::pcm_wav_header(u32::try_from(data_len).unwrap_or(u32::MAX), channels, rate, 16);
v.reserve(data_len);
for s in samples {
v.extend_from_slice(&((s.clamp(-1.0, 1.0) * 32767.0).round() as i16).to_le_bytes());
}
v
}
#[cfg(all(test, feature = "pcm-encode"))]
mod tests {
use super::*;
use std::sync::{Arc, Mutex};
struct Source {
bytes: Vec<u8>,
reads: Arc<Mutex<Vec<(u64, usize)>>>,
}
impl ByteSource for Source {
fn len(&self) -> u64 {
self.bytes.len() as u64
}
fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> {
self.reads.lock().unwrap_or_else(std::sync::PoisonError::into_inner).push((offset, buf.len()));
self.bytes.read_at(offset, buf)
}
}
#[test]
fn bounded_reads_and_pcm_values() {
let bytes = write_wav16(&[-1.0, -0.5, 0.0, 0.5, 1.0], 1, 48_000);
let reads = Arc::new(Mutex::new(Vec::new()));
let wav = WavRange::open(Source { bytes, reads: reads.clone() }, 64, 384_000).unwrap();
assert_eq!((wav.frames, wav.channels, wav.rate, wav.bits), (5, 1, 48_000, 16));
assert!(reads.lock().unwrap().iter().all(|(_, n)| *n <= 40));
let data = wav.read_frames(1, 3).unwrap();
assert_eq!(wav.sample(&data, 0, 0), -0.5);
assert_eq!(wav.sample(&data, 2, 0), 0.5);
assert!(wav.read_frames(0, 5).is_err());
assert!(wav.read_frames(3, 1).is_err());
assert_eq!(reads.lock().unwrap().last(), Some(&(46, 6)));
}
#[test]
fn ixml_fallback_accepts_flat_fields() {
let base = write_wav16(&[0.0], 1, 48_000);
let mut bytes = base[..36].to_vec();
let xml = b"<BWF_TIME_REFERENCE_LOW>5</BWF_TIME_REFERENCE_LOW><BWF_TIME_REFERENCE_HIGH>1</BWF_TIME_REFERENCE_HIGH>";
bytes.extend_from_slice(b"iXML");
bytes.extend_from_slice(&(xml.len() as u32).to_le_bytes());
bytes.extend_from_slice(xml);
if xml.len() & 1 != 0 {
bytes.push(0);
}
bytes.extend_from_slice(&base[36..]);
assert_eq!(WavRange::open(bytes.as_slice(), 64, 384_000).unwrap().time_reference, Some((1 << 32) + 5));
}
}
+17 -10
View File
@@ -12,7 +12,7 @@ mod pcm;
#[cfg(feature = "vorbis-encode")]
mod vorbis;
#[cfg(feature = "vorbis-encode")]
pub use vorbis::{OGG_BITRATES, encode as encode_ogg};
pub use vorbis::{OGG_BITRATES, OggVorbisOptions, encode as encode_ogg, encode_ogg_vorbis, quality_for_bitrate};
#[cfg(feature = "pcm-encode")]
mod raw;
#[cfg(feature = "pcm-encode")]
@@ -66,15 +66,22 @@ pub fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result<Vec<u8>> {
EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Mp3 | EncodeFormat::Ac3 | EncodeFormat::Eac3 => coded::encode(buf, opts),
#[cfg(feature = "vorbis-encode")]
EncodeFormat::Ogg => {
if opts.layout.is_some_and(|layout| !EncodeFormat::Ogg.supports_layout(&layout)) {
return Err(AudioError::Unsupported("Vorbis requires a mono or stereo speaker layout".into()));
let count = u16::try_from(buf.channels.len()).unwrap_or(u16::MAX);
let layout = opts.layout.unwrap_or_else(|| ChannelLayout::default_for(count));
if layout.channels() != count {
return Err(AudioError::Unsupported(format!("a {}-channel layout for {count} channels", layout.channels())));
}
let kbps = match opts.rate_control {
None => 192,
Some(crate::RateControl::Bitrate(bps)) => bps / 1000,
Some(crate::RateControl::Quality(_)) => return Err(AudioError::Unsupported("Ogg export takes a target bitrate".into())),
let map = vorbis::vorbis_map(&layout)?;
let quality = match opts.rate_control {
None => vorbis::quality_for_bitrate(192, buf.channels.len()),
Some(crate::RateControl::Bitrate(bps)) => {
vorbis::quality_for_bitrate((bps / 1000).clamp(OGG_BITRATES.0, OGG_BITRATES.1), buf.channels.len())
}
Some(crate::RateControl::Quality(q)) if q.is_nan() => return Err(AudioError::Encode("the Vorbis quality is NaN".into())),
Some(crate::RateControl::Quality(q)) => -1.0 + 11.0 * q.clamp(0.0, 1.0),
};
vorbis::encode(buf, kbps)
let planar: Vec<&[f32]> = map.iter().filter_map(|&i| buf.channels.get(i).map(Vec::as_slice)).collect();
vorbis::encode_planar(buf.sample_rate, &planar, &OggVorbisOptions::new(quality))
}
#[allow(unreachable_patterns)]
f => Err(AudioError::Unsupported(format!("writing {f:?}"))),
@@ -106,7 +113,7 @@ const fn extensions() -> ([&'static str; 13], usize) {
add!(cfg!(feature = "mp3-encode"), "mp3");
add!(cfg!(feature = "ac3-encode"), "ac3");
add!(cfg!(feature = "eac3-encode"), "eac3", "ec3");
add!(cfg!(all(feature = "vorbis-encode", not(target_arch = "wasm32"))), "ogg");
add!(cfg!(feature = "vorbis-encode"), "ogg");
(all, n)
}
@@ -148,7 +155,7 @@ pub fn encode_format_for(name: &str) -> Option<EncodeFormat> {
"ac3" => Some(EncodeFormat::Ac3),
#[cfg(feature = "eac3-encode")]
"eac3" | "ec3" => Some(EncodeFormat::Eac3),
#[cfg(all(feature = "vorbis-encode", not(target_arch = "wasm32")))]
#[cfg(feature = "vorbis-encode")]
"ogg" => Some(EncodeFormat::Ogg),
_ => None,
}
+217 -80
View File
@@ -1,83 +1,198 @@
//! Ogg Vorbis encoding (RFC 5334): the reference libvorbis encoder, built from its C sources by
//! `vorbis_rs`. Stereo or mono, variable bitrate at the requested kbit/s (64–500), with a
//! fallback to a quality preset when the bitrate is not supported for the rate and channel count.
//! Ogg Vorbis files (Vorbis I §A, RFC 5334) from the pure-Rust [`crate::vorbis::encoder`] and
//! craft-media's Ogg page writer: 1 to 8 channels in Vorbis channel order, a quality from -1 to
//! 10 (variable bit rate), and the tags in the comment header. Builds for every target.
use crate::{AudioBuffer, AudioError, Result};
use craft_media::ogg::{PageWriter, vorbis_comment};
/// The bitrates an Ogg Vorbis export is asked for, in kbit/s.
use crate::vorbis::encoder::{DEFAULT_QUALITY, Encoder, EncoderConfig, Error as VorbisError};
use crate::{AudioBuffer, AudioError, ChannelLayout, Result};
/// The bit rates [`encode_ogg`](crate::encode_ogg) takes, in kbit/s. Vorbis is variable: the bit rate picks a
/// quality ([`quality_for_bitrate`]), and the file comes out near it for typical music.
pub const OGG_BITRATES: (u32, u32) = (64, 500);
/// The block size the encoder processes at a time: small enough that memory stays bounded
/// regardless of file length.
#[cfg(not(target_arch = "wasm32"))]
const BLOCK: usize = 4096;
/// The serial number of the stream when the options do not set one (`LCRF`): one stream per file,
/// so a constant keeps files byte-for-byte reproducible.
const SERIAL: u32 = 0x4C43_5246;
#[cfg(not(target_arch = "wasm32"))]
fn encode_error(e: vorbis_rs::VorbisError) -> AudioError {
AudioError::Encode(e.to_string())
/// Samples per channel fed to the encoder at a time.
const CHUNK: usize = 4096;
/// What [`encode_ogg_vorbis`] writes besides the audio.
///
/// `#[non_exhaustive]`: build it with `OggVorbisOptions::default()` or
/// [`OggVorbisOptions::new`] and the `with_*` methods.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
pub struct OggVorbisOptions {
/// -1 (smallest) to 10 (best); clamped, and NaN or infinite reads as
/// [`DEFAULT_QUALITY`] (6).
pub quality: f32,
/// The comment header's vendor string.
pub vendor: String,
/// `NAME=value` comments (Vorbis I §5), in order. A name that is empty, or holds `=` or a byte
/// outside 0x20–0x7D, is left out.
pub tags: Vec<(String, String)>,
/// The logical stream's serial number.
pub serial: u32,
}
/// Encode `buf` as an Ogg Vorbis stream at about `kbps` (variable, as Vorbis is): stereo, or mono
/// for a mono buffer. A bitrate the encoder has no setup for at that rate and channel count falls
/// back to a quality that suits it. `Err` says why there is nothing.
#[cfg(not(target_arch = "wasm32"))]
pub fn encode(buf: &AudioBuffer, kbps: u32) -> Result<Vec<u8>> {
use std::num::{NonZeroU8, NonZeroU32};
let channels = buf.channels.len();
if !(1..=2).contains(&channels) {
return Err(AudioError::Unsupported("Ogg Vorbis export requires mono or stereo audio".into()));
impl Default for OggVorbisOptions {
fn default() -> Self {
OggVorbisOptions { quality: DEFAULT_QUALITY, vendor: "craft-audio".into(), tags: Vec::new(), serial: SERIAL }
}
if buf.channels.iter().any(|c| c.len() != buf.frames() || c.iter().any(|s| !s.is_finite())) {
}
impl OggVorbisOptions {
/// The defaults at `quality`.
pub fn new(quality: f32) -> Self {
OggVorbisOptions { quality, ..Self::default() }
}
/// Sets [`quality`](Self::quality).
pub fn with_quality(mut self, quality: f32) -> Self {
self.quality = quality;
self
}
/// Sets [`vendor`](Self::vendor).
pub fn with_vendor(mut self, vendor: impl Into<String>) -> Self {
self.vendor = vendor.into();
self
}
/// Adds a comment ([`tags`](Self::tags)).
pub fn with_tag(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
self.tags.push((name.into(), value.into()));
self
}
/// Sets [`serial`](Self::serial).
pub fn with_serial(mut self, serial: u32) -> Self {
self.serial = serial;
self
}
}
fn encode_error(e: VorbisError) -> AudioError {
AudioError::Encode(format!("Vorbis: {e}"))
}
/// Encode `buf` as an Ogg Vorbis file with `opts`. The channels are in Vorbis channel order
/// (Vorbis I §4.3.9: L C R for three, L C R Ls Rs LFE for 5.1, L C R Ls Rs Rl Rr LFE for 7.1).
/// The last granule position is the buffer's length, so a decoder returns exactly its frames.
///
/// ```
/// use craft_audio::{AudioBuffer, OggVorbisOptions, encode_ogg_vorbis};
///
/// let buf = AudioBuffer::new(48_000, 6, 4_800); // 0.1 s of 5.1 silence
/// let opts = OggVorbisOptions::new(4.0).with_tag("TITLE", "Silence");
/// let ogg = encode_ogg_vorbis(&buf, &opts).unwrap();
/// assert!(ogg.starts_with(b"OggS"));
/// ```
pub fn encode_ogg_vorbis(buf: &AudioBuffer, opts: &OggVorbisOptions) -> Result<Vec<u8>> {
let planar: Vec<&[f32]> = buf.channels.iter().map(Vec::as_slice).collect();
encode_planar(buf.sample_rate, &planar, opts)
}
/// [`encode_ogg_vorbis`] over channels already in Vorbis order.
pub(crate) fn encode_planar(sample_rate: u32, planar: &[&[f32]], opts: &OggVorbisOptions) -> Result<Vec<u8>> {
if !(1..=8).contains(&planar.len()) {
return Err(AudioError::Unsupported(format!("Ogg Vorbis holds 1 to 8 channels, not {}", planar.len())));
}
let frames = planar.first().map_or(0, |c| c.len());
if planar.iter().any(|c| c.len() != frames || c.iter().any(|s| !s.is_finite())) {
return Err(AudioError::Encode("Vorbis samples must be finite and channels equally long".into()));
}
let (Some(rate), Some(count)) = (NonZeroU32::new(buf.sample_rate), NonZeroU8::new(channels as u8)) else {
if sample_rate == 0 {
return Err(AudioError::Encode("there is no audio to encode".into()));
};
let target = NonZeroU32::new(kbps.clamp(OGG_BITRATES.0, OGG_BITRATES.1) * 1000).unwrap_or(NonZeroU32::MIN);
let encode = |strategy: vorbis_rs::VorbisBitrateManagementStrategy| -> Result<Vec<u8>> {
let mut encoder = vorbis_rs::VorbisEncoderBuilder::new_with_serial(rate, count, Vec::new(), 0x4C43_5246)
.bitrate_management_strategy(strategy)
.build()
.map_err(encode_error)?;
let frames = buf.frames();
let mut at = 0usize;
while at < frames {
let end = (at + BLOCK).min(frames);
let block: Vec<&[f32]> = buf.channels.iter().take(channels).map(|side| side.get(at..end).unwrap_or_default()).collect();
encoder.encode_audio_block(&block).map_err(encode_error)?;
at = end;
}
let mut enc = Encoder::new(EncoderConfig::new(sample_rate, planar.len(), opts.quality)).map_err(encode_error)?;
let mut pages = PageWriter::new(opts.serial);
let tags: Vec<(&str, &str)> = opts.tags.iter().map(|(k, v)| (k.as_str(), v.as_str())).collect();
let mut out = pages.header(&enc.identification());
out.extend(pages.header(&vorbis_comment(&opts.vendor, &tags)));
out.extend(pages.header(&enc.setup()));
// The first audio packet (which outputs nothing) gets a page of its own: a stream whose first
// audio page is also its last would leave decoders to choose between start and end trimming
// (Vorbis I §A.2), and ffmpeg then plays the padding.
let mut first = true;
let mut add = |packets: Vec<(Vec<u8>, i64)>, out: &mut Vec<u8>| {
for (packet, granule) in packets {
out.extend(pages.packet(&packet, granule));
if std::mem::take(&mut first) {
out.extend(pages.flush());
}
}
encoder.finish().map_err(encode_error)
};
let mut at = 0;
loop {
let end = (at + CHUNK).min(frames);
let chunk: Vec<&[f32]> = planar.iter().map(|c| c.get(at..end).unwrap_or_default()).collect();
add(enc.encode(&chunk).map_err(encode_error)?, &mut out);
at = end;
if at >= frames {
break;
}
}
add(enc.finish().map_err(encode_error)?, &mut out);
out.extend(pages.finish(None));
Ok(out)
}
// Convert Rust unwinds to an error. This does not catch native crashes or aborts.
let attempt = |strategy| {
std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| encode(strategy)))
.unwrap_or_else(|_| Err(AudioError::Encode("the Vorbis encoder failed".into())))
};
match attempt(vorbis_rs::VorbisBitrateManagementStrategy::Vbr { target_bitrate: target }) {
Ok(bytes) => Ok(bytes),
Err(_) => attempt(vorbis_rs::VorbisBitrateManagementStrategy::QualityVbr { target_quality: 0.6 })
.map_err(|e| AudioError::Encode(format!("the Vorbis encoder refused the audio: {e}"))),
/// Nominal kbit/s per channel at each whole quality from -1 to 10: this encoder's rate on
/// music-like test signals at 48 kHz (harmonic chords with noise), averaged.
const KBPS_PER_CHANNEL: [f32; 12] = [18.0, 23.0, 31.0, 43.0, 58.0, 75.0, 89.0, 100.0, 111.0, 121.0, 130.0, 140.0];
/// The quality whose nominal bit rate is `kbps` kbit/s for `channels` channels (clamped to -1..=10).
/// Vorbis is variable: the bit rate of a file depends on the audio.
pub fn quality_for_bitrate(kbps: u32, channels: usize) -> f32 {
let per = kbps as f32 / channels.max(1) as f32;
let mut q = -1.0;
for pair in KBPS_PER_CHANNEL.windows(2) {
if let [lo, hi] = *pair
&& per <= hi
{
return q + ((per - lo) / (hi - lo)).clamp(0.0, 1.0);
}
q += 1.0;
}
10.0
}
/// Encode `buf` as an Ogg Vorbis stream near `kbps` kbit/s ([`OGG_BITRATES`], clamped): the
/// quality [`quality_for_bitrate`] gives, no tags. 1 to 8 channels in Vorbis channel order.
/// `Err` says why there is nothing.
pub fn encode(buf: &AudioBuffer, kbps: u32) -> Result<Vec<u8>> {
let kbps = kbps.clamp(OGG_BITRATES.0, OGG_BITRATES.1);
encode_ogg_vorbis(buf, &OggVorbisOptions::new(quality_for_bitrate(kbps, buf.channels.len())))
}
/// WAV-order speakers ([`crate::EncodeFormat::layout_masks`]) to Vorbis order, per channel count.
const VORBIS_ORDER: [&[usize]; 8] =
[&[0], &[0, 1], &[0, 2, 1], &[0, 1, 2, 3], &[0, 2, 1, 3, 4], &[0, 2, 1, 4, 5, 3], &[0, 2, 1, 5, 6, 4, 3], &[0, 2, 1, 6, 7, 4, 5, 3]];
/// For each Vorbis channel, the channel of audio in `layout` it comes from.
pub(crate) fn vorbis_map(layout: &ChannelLayout) -> Result<Vec<usize>> {
let n = layout.channels();
let mask = crate::EncodeFormat::Ogg.layout_masks(n).first().copied();
let order = usize::from(n).checked_sub(1).and_then(|i| VORBIS_ORDER.get(i)).copied();
match (mask, order) {
(Some(mask), Some(order)) => crate::layout::channel_map(mask, Some(order), layout)
.ok_or_else(|| AudioError::Unsupported(format!("Vorbis has no layout of {n} channels with these speakers"))),
_ => Err(AudioError::Unsupported(format!("Ogg Vorbis holds 1 to 8 channels, not {n}"))),
}
}
/// Ogg Vorbis encoding is unavailable on WASM; returns an unsupported-format error.
#[cfg(target_arch = "wasm32")]
pub fn encode(_buf: &AudioBuffer, _kbps: u32) -> Result<Vec<u8>> {
Err(AudioError::Unsupported("Ogg Vorbis files are exported by the desktop app".into()))
}
#[cfg(all(test, not(target_arch = "wasm32")))]
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used)]
use super::*;
use super::{OGG_BITRATES, OggVorbisOptions, encode, encode_ogg_vorbis, quality_for_bitrate, vorbis_map};
use crate::{AudioBuffer, AudioError, ChannelLayout};
#[test]
fn rejects_unsupported_or_malformed_channels_without_dropping_audio() {
for channels in [0, 3, 6] {
for channels in [0, 9] {
assert!(matches!(encode(&AudioBuffer::new(48_000, channels, 16), 192), Err(AudioError::Unsupported(_))));
}
let ragged = AudioBuffer { sample_rate: 48_000, channels: vec![vec![0.0; 16], vec![0.0; 15]] };
@@ -85,46 +200,68 @@ mod tests {
assert!(encode(&AudioBuffer::new(0, 1, 16), 192).is_err());
let invalid = AudioBuffer { sample_rate: 48_000, channels: vec![vec![f32::NAN]] };
assert!(encode(&invalid, 192).is_err());
let infinite = AudioBuffer { sample_rate: 48_000, channels: vec![vec![f32::INFINITY]] };
assert!(encode(&infinite, 192).is_err());
}
#[test]
fn generic_and_direct_encoders_write_mono_and_stereo_ogg() {
for channels in [1, 2] {
fn generic_and_direct_encoders_write_one_to_eight_channels() {
for channels in 1..=8 {
let audio = AudioBuffer::new(48_000, channels, 512);
let opts = crate::EncodeOptions::new(crate::EncodeFormat::Ogg);
assert!(opts.check(48_000, channels).is_ok());
assert_eq!(opts.bitrate(48_000, channels).unwrap(), None);
let direct = encode(&audio, 192).unwrap();
let generic = crate::encode(&audio, &opts).unwrap();
assert!(direct.starts_with(b"OggS"));
assert_eq!(direct, generic);
// silence: the channel order changes nothing, so the generic path writes the same file
let generic = crate::encode(&audio, &opts.with_bitrate(192_000)).unwrap();
assert_eq!(direct, generic, "{channels} channels");
#[cfg(feature = "decode")]
{
let (info, decoded) = crate::decode(&generic, Some("ogg")).unwrap();
assert_eq!(info.channels, channels);
assert_eq!(decoded.num_channels(), channels);
assert_eq!(decoded.frames(), audio.frames());
}
}
}
#[cfg(feature = "decode")]
#[test]
fn distinct_signals_survive_full_and_partial_blocks() {
for frames in [4096, 4097, 8193] {
let channels: Vec<Vec<f32>> = [440.0f32, 880.0]
.into_iter()
.map(|hz| (0..frames).map(|i| (std::f32::consts::TAU * hz * i as f32 / 48_000.0).sin() * 0.4).collect())
.collect();
let audio = AudioBuffer { sample_rate: 48_000, channels };
let bytes = encode(&audio, 192).unwrap();
let (_, decoded) = crate::decode(&bytes, Some("ogg")).unwrap();
assert_eq!(decoded.frames(), frames);
assert_eq!(decoded.channels.len(), 2);
for (expected, actual) in audio.channels.iter().zip(&decoded.channels) {
let mse = expected.iter().zip(actual).map(|(a, b)| (a - b).powi(2)).sum::<f32>() / frames as f32;
// Vorbis is lossy; this tolerates codec error but rejects silence or swapped channels.
assert!(mse.sqrt() < 0.08, "{frames} frames: RMS error {}", mse.sqrt());
}
fn the_quality_follows_the_bit_rate() {
assert_eq!(quality_for_bitrate(0, 2), -1.0);
assert_eq!(quality_for_bitrate(10_000, 2), 10.0);
assert!((quality_for_bitrate(200, 2) - 6.0).abs() < 1e-6);
assert!((quality_for_bitrate(600, 6) - 6.0).abs() < 1e-6);
let mut last = -2.0;
for kbps in OGG_BITRATES.0..=OGG_BITRATES.1 {
let q = quality_for_bitrate(kbps, 2);
assert!(q >= last && (-1.0..=10.0).contains(&q));
last = q;
}
assert!(quality_for_bitrate(192, 0).is_finite());
}
#[test]
fn layouts_map_to_vorbis_order() {
// 5.1 in WAV order (L R C LFE Ls Rs) is written L C R Ls Rs LFE
assert_eq!(vorbis_map(&ChannelLayout::SURROUND_5_1).unwrap(), [0, 2, 1, 4, 5, 3]);
assert_eq!(vorbis_map(&ChannelLayout::SURROUND_5_1_SIDE).unwrap(), [0, 2, 1, 4, 5, 3]);
assert_eq!(vorbis_map(&ChannelLayout::from_mask(0x63F)).unwrap(), [0, 2, 1, 6, 7, 4, 5, 3]);
assert_eq!(vorbis_map(&ChannelLayout::from_mask(0x7)).unwrap(), [0, 2, 1]);
assert_eq!(vorbis_map(&ChannelLayout::STEREO).unwrap(), [0, 1]);
assert!(vorbis_map(&ChannelLayout::from_mask(0xC)).is_err());
assert!(vorbis_map(&ChannelLayout::unordered(9)).is_err());
assert!(vorbis_map(&ChannelLayout::unordered(0)).is_err());
}
#[test]
fn options_build_and_tags_reach_the_comment_header() {
let opts = OggVorbisOptions::default().with_quality(2.0).with_vendor("v").with_tag("TITLE", "t").with_tag("bad=name", "x").with_serial(9);
assert_eq!((opts.quality, opts.vendor.as_str(), opts.serial, opts.tags.len()), (2.0, "v", 9, 2));
let ogg = encode_ogg_vorbis(&AudioBuffer::new(44_100, 1, 100), &opts).unwrap();
let file = craft_media::ogg::open(&ogg).unwrap();
let s = &file.streams[0];
assert_eq!((s.serial, s.saw_eos, s.headers.len()), (9, true, 3));
assert_eq!(s.headers[1], craft_media::ogg::vorbis_comment("v", &[("TITLE", "t")]));
assert_eq!(s.last_granule, Some(100));
}
}
+2 -2
View File
@@ -20,8 +20,8 @@ fn only_formats_the_encoder_writes_are_named() {
}
#[test]
fn ogg_names_follow_the_native_feature() {
let built = cfg!(all(feature = "vorbis-encode", not(target_arch = "wasm32")));
fn ogg_names_follow_the_feature() {
let built = cfg!(feature = "vorbis-encode");
assert_eq!(EncodeFormat::Ogg.is_built(), built);
assert_eq!(encode_format_for("ogg"), built.then_some(EncodeFormat::Ogg));
assert_eq!(craft_audio::ENCODE_EXTENSIONS.contains(&"ogg"), built);
+1 -1
View File
@@ -527,7 +527,7 @@ fn the_format_queries_agree_with_the_writer() {
// The most channels is the most: one more is refused, by the layouts of a format that has
// a fixed set and by the writer of one that has not.
let most: Vec<u16> = EncodeFormat::ALL.iter().map(|f| f.max_channels()).collect();
assert_eq!(most, [32_767, 32_767, 8, 8, 8, 2, 6, 8, 2]);
assert_eq!(most, [32_767, 32_767, 8, 8, 8, 2, 6, 8, 8]);
for &format in EncodeFormat::ALL {
let most = format.max_channels();
match format.fixed_layouts(most) {
+2
View File
@@ -20,3 +20,5 @@ mod opus;
mod opusenc;
mod routing_oracle;
mod track_decoder;
#[cfg(feature = "vorbis-encode")]
mod vorbis_encoder_oracle;
@@ -0,0 +1,131 @@
//! ffmpeg as an external oracle for the pure-Rust Vorbis encoder: both of its decoders (its own
//! and libvorbis) read every file exactly as long as the input, surround comes out on the right
//! speakers, and the tags reach ffprobe. Skipped when ffmpeg is not installed.
use std::path::Path;
use std::process::Command;
use craft_audio::{AudioBuffer, ChannelLayout, EncodeFormat, EncodeOptions, OggVorbisOptions, encode, encode_ogg_vorbis};
/// A different tone on every channel, so each output channel can be traced to its input.
fn tones(rate: u32, channels: usize, frames: usize) -> AudioBuffer {
let channels = (0..channels)
.map(|c| {
let f = 220.0 * (c + 1) as f32;
(0..frames).map(|i| (std::f32::consts::TAU * f * i as f32 / rate as f32).sin() * 0.3).collect()
})
.collect();
AudioBuffer { sample_rate: rate, channels }
}
/// Decodes `file` with ffmpeg's `decoder`; planar output in ffmpeg's (WAV) channel order.
fn ffmpeg_decode(ff: &Path, decoder: &str, file: &[u8], channels: usize, tag: &str) -> Vec<Vec<f32>> {
let path = crate::testkit::fixtures_dir("vorbis-encoder").join(format!("{tag}.ogg"));
std::fs::write(&path, file).unwrap();
let out = Command::new(ff)
.args(["-v", "error", "-xerror", "-c:a", decoder, "-i"])
.arg(&path)
.args(["-f", "f32le", "-c:a", "pcm_f32le", "-"])
.output()
.unwrap();
assert!(out.status.success() && out.stderr.is_empty(), "{tag} {decoder}: {}", String::from_utf8_lossy(&out.stderr));
let pcm: Vec<f32> = out.stdout.as_chunks::<4>().0.iter().map(|&b| f32::from_le_bytes(b)).collect();
(0..channels).map(|c| pcm.iter().skip(c).step_by(channels).copied().collect()).collect()
}
/// ffmpeg's decoders to check: its own `vorbis` always, and `libvorbis` when ffmpeg has it.
fn decoders(ff: &Path) -> Vec<&'static str> {
let list =
Command::new(ff).args(["-hide_banner", "-decoders"]).output().map(|o| String::from_utf8_lossy(&o.stdout).into_owned()).unwrap_or_default();
if list.lines().any(|l| l.split_whitespace().nth(1) == Some("libvorbis")) {
vec!["vorbis", "libvorbis"]
} else {
eprintln!("SKIPPED (libvorbis decoder): this ffmpeg has no libvorbis; checking its own decoder only");
vec!["vorbis"]
}
}
fn correlation(a: &[f32], b: &[f32]) -> f64 {
let (mut ab, mut aa, mut bb) = (0f64, 0f64, 0f64);
for (&x, &y) in a.iter().zip(b) {
ab += f64::from(x) * f64::from(y);
aa += f64::from(x) * f64::from(x);
bb += f64::from(y) * f64::from(y);
}
ab / (aa * bb).sqrt().max(1e-20)
}
/// Vorbis order (§4.3.9) of the WAV-order layouts the test writes, per channel count.
const VORBIS_ORDER: [&[usize]; 8] =
[&[0], &[0, 1], &[0, 2, 1], &[0, 1, 2, 3], &[0, 2, 1, 3, 4], &[0, 2, 1, 4, 5, 3], &[0, 2, 1, 5, 6, 4, 3], &[0, 2, 1, 6, 7, 4, 5, 3]];
/// 1 to 8 channels through `encode` with a WAV-order layout, at exactly the input's length out of
/// both decoders: ffmpeg's own puts every channel back on its WAV speaker, and libvorbis (through
/// ffmpeg, which passes its order through) gives the file's Vorbis order.
#[test]
fn every_channel_count_decodes_on_the_right_speakers() {
let ff = require_ffmpeg!();
for channels in 1..=8u16 {
let layout = if channels == 7 { ChannelLayout::from_mask(0x70F) } else { ChannelLayout::default_for(channels) };
let buf = tones(48_000, channels.into(), 24_000 + 77);
let opts = EncodeOptions::new(EncodeFormat::Ogg).with_layout(layout).with_quality(0.6);
let file = encode(&buf, &opts).unwrap();
for decoder in decoders(&ff) {
let out = ffmpeg_decode(&ff, decoder, &file, channels.into(), &format!("tones{channels}-{decoder}"));
for (j, got) in out.iter().enumerate() {
let c = if decoder == "libvorbis" { VORBIS_ORDER[usize::from(channels) - 1][j] } else { j };
assert_eq!(got.len(), buf.frames(), "{channels} ch {decoder}: channel {j} length");
let best = (0..buf.channels.len()).max_by(|&a, &b| {
correlation(&buf.channels[a][2048..], &got[2048..]).total_cmp(&correlation(&buf.channels[b][2048..], &got[2048..]))
});
assert_eq!(best, Some(c), "{channels} ch {decoder}: output channel {c} carries input {best:?}");
let r = correlation(&buf.channels[c][2048..], &got[2048..]);
assert!(r > 0.95, "{channels} ch {decoder}: channel {c} correlation {r:.3}");
}
}
}
}
/// The comment header's tags, UTF-8 values included, are what ffprobe reports; a name that is not
/// a valid field name is left out.
#[test]
fn tags_reach_ffprobe() {
let Some(probe) = crate::common::tool("ffprobe").or_else(|| crate::common::skip("ffprobe not found")) else { return };
let opts = OggVorbisOptions::new(3.0)
.with_tag("TITLE", "Smörgåsbord ✓")
.with_tag("ARTIST", "Craft")
.with_tag("bad=name", "dropped")
.with_vendor("craft-audio test");
let file = encode_ogg_vorbis(&tones(44_100, 2, 44_100), &opts).unwrap();
let path = crate::testkit::fixtures_dir("vorbis-encoder").join("tags.ogg");
std::fs::write(&path, &file).unwrap();
let out = Command::new(probe).args(["-v", "error", "-of", "json", "-show_streams", "-show_format"]).arg(&path).output().unwrap();
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
let j: serde_json::Value = serde_json::from_slice(&out.stdout).unwrap();
let s = &j["streams"][0];
assert_eq!((s["codec_name"].as_str(), s["channels"].as_u64(), s["sample_rate"].as_str()), (Some("vorbis"), Some(2), Some("44100")));
let tags = &s["tags"];
assert_eq!((tags["TITLE"].as_str(), tags["ARTIST"].as_str()), (Some("Smörgåsbord ✓"), Some("Craft")));
assert!(tags.as_object().unwrap().keys().all(|k| !k.contains("bad")), "{tags}");
assert_eq!(j["format"]["duration"].as_str().map(|d| d.parse::<f64>().unwrap()), Some(1.0));
}
/// The lowest and highest qualities and the bit-rate path decode at the exact length, mono at
/// 44.1 kHz and stereo at 22.05 kHz.
#[test]
fn quality_extremes_and_rates_decode_exactly() {
let ff = require_ffmpeg!();
for (rate, channels, quality) in [(44_100u32, 1usize, -1.0f32), (44_100, 1, 10.0), (22_050, 2, -1.0), (22_050, 2, 10.0), (96_000, 2, 5.0)] {
let buf = tones(rate, channels, rate as usize / 2 + 13);
let file = encode_ogg_vorbis(&buf, &OggVorbisOptions::new(quality)).unwrap();
for decoder in decoders(&ff) {
let out = ffmpeg_decode(&ff, decoder, &file, channels, &format!("q{quality}-{rate}-{channels}-{decoder}"));
assert!(out.iter().all(|c| c.len() == buf.frames()), "q{quality} {rate} Hz {decoder}: {}", out[0].len());
let r = correlation(&buf.channels[0][2048..], &out[0][2048..]);
assert!(r > 0.9, "q{quality} {rate} Hz {decoder}: correlation {r:.3}");
}
}
let low = craft_audio::encode_ogg(&tones(48_000, 2, 48_000), craft_audio::OGG_BITRATES.0).unwrap();
let high = craft_audio::encode_ogg(&tones(48_000, 2, 48_000), craft_audio::OGG_BITRATES.1).unwrap();
assert!(low.len() < high.len(), "{} vs {} bytes", low.len(), high.len());
}
+62
View File
@@ -0,0 +1,62 @@
//! QOA against ffmpeg's decoder as the reference (oracle; skipped when ffmpeg is absent, a failure
//! with `CRAFT_MEDIA_REQUIRE_ORACLES=1`): ffmpeg decodes the files our encoder writes to exactly
//! the samples our decoder returns for them, over several sizes (partial slices, partial frames,
//! several frames), channel counts and rates.
use craft_audio::qoa::{decode, encode};
use std::process::Command;
fn signal(channels: usize, frames: usize) -> Vec<Vec<i16>> {
let mut seed = 0x2545_F491u32;
(0..channels)
.map(|c| {
(0..frames)
.map(|i| {
seed ^= seed << 13;
seed ^= seed >> 17;
seed ^= seed << 5;
let tone = ((i as f64) * (0.02 + 0.013 * c as f64)).sin() * 9000.0;
// Tones, noise bursts, silence and full-scale peaks.
match (i / 700) % 4 {
0 => tone as i16,
1 => (tone + f64::from(seed % 6000) - 3000.0) as i16,
2 => 0,
_ => {
if i % 2 == 0 {
i16::MAX
} else {
i16::MIN
}
}
}
})
.collect()
})
.collect()
}
#[test]
fn ffmpeg_decodes_our_files_to_the_same_samples() {
let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("qoa");
for (rate, channels, frames) in
[(44_100u32, 1usize, 1usize), (8_000, 1, 19), (48_000, 2, 5_121), (22_050, 2, 12_345), (96_000, 1, 20_000), (44_100, 4, 6_000)]
{
let src = signal(channels, frames);
let bytes = encode(rate, &src).expect("encode");
let ours = decode(&bytes).expect("decode");
let file = dir.join(format!("ours_{rate}_{channels}_{frames}.qoa"));
std::fs::write(&file, &bytes).expect("write fixture");
let out = Command::new(&ffmpeg)
.args(["-v", "error", "-y", "-i"])
.arg(&file)
.args(["-f", "s16le", "-acodec", "pcm_s16le", "-"])
.output()
.expect("run ffmpeg");
assert!(out.status.success(), "ffmpeg failed on {}: {}", file.display(), String::from_utf8_lossy(&out.stderr));
let theirs: Vec<i16> = out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect();
let interleaved: Vec<i16> = (0..frames).flat_map(|i| ours.channels.iter().map(move |ch| ch[i])).collect();
assert_eq!(theirs.len(), interleaved.len(), "{rate} Hz, {channels} ch, {frames} frames: sample count");
assert!(theirs == interleaved, "{rate} Hz, {channels} ch, {frames} frames: samples differ");
}
}
+2
View File
@@ -19,3 +19,5 @@ thiserror = { workspace = true }
proptest = { workspace = true }
# A second XML reader for the tests: checks of written TTML, and the comparison in tests/it/ttml_xml_views.rs.
roxmltree = "0.21"
# ffmpeg as the reference for the ASS tests (tests/it/ass.rs).
craft-media-testkit = { workspace = true }
+1
View File
@@ -55,6 +55,7 @@ lists at most 20 characters per stream.
| EBU STL `.stl` | yes | yes | EBU Tech 3264-E: GSI block + 128-byte TTI blocks, `STL25.01` (25 fps) or `STL30.01` (read/written as 29.97 fps, non-drop labels), ISO/IEC 6937 Latin text (accents as diacritic + letter), italics / underline codes as `<i>` / `<u>`, extension blocks for long subtitles, start-of-programme (TCP) subtracted. |
| TTML `.ttml` (IMSC1) | yes | yes | Writes the IMSC1 Text profile (TTML2 namespaces) with the document's language as `xml:lang` (read back on import): `<p>` per cue, `<br/>`, styled `<span>`s for `<i>` / `<b>` / `<u>`, `ttm:agent` speakers, exact frame times (`123f`) at the sequence rate. Reads any TTML (TTML1, TTML2, the 2006 `ttaf1` drafts): clock / frame / offset / tick times, `dur`, nested time containers (`body` / `div` begins offset and ends clip their contents; `seq` containers are read as `par` with a warning), timed spans, referenced styles. |
| DFXP `.dfxp` | yes | yes | TTML1 with the DFXP presentation profile; clock times in milliseconds (frame-exact after `snap_to_frames`). |
| ASS / SSA `.ass`, `.ssa` | yes | yes (ASS v4+) | The `[Events]` section: `Dialogue:` lines through the file's `Format:` line, `Name` as the speaker, `\N`, `\n`, `\h` and the `\i`, `\b`, `\u` override tags kept (as `<i>`, `<b>`, `<u>`); other override tags and drawing lines are dropped. Times are centiseconds. Written files have one `Default` style. |
All cue times are exact `Tick`s. Milliseconds convert exactly (1 ms = 254 016 000 ticks); SCC
frames map through `FrameRate::FPS_29_97`. `Document::snap_to_frames` snaps cues to a frame grid and
+244
View File
@@ -0,0 +1,244 @@
//! Advanced SubStation Alpha and SubStation Alpha (`.ass`, `.ssa`).
//!
//! Reading takes the `[Events]` section: its `Format:` line gives the field order (ASS v4+ and SSA
//! v4 differ in the first field only), each `Dialogue:` line becomes a cue; `Comment:` lines and
//! the other sections are skipped. A cue gets the `Name` field as its speaker. The text keeps what
//! the neutral model can show: `\N` and `\n` become a line break and a space, `\h` a no-break
//! space, and the override tags `\i`, `\b` and `\u` become `<i>`, `<b>` and `<u>`. Every other
//! override tag (colours, fonts, positions, karaoke, animation) is dropped, and a line that draws
//! vector shapes (`\p1`) is skipped with a warning.
//!
//! Writing gives a minimal ASS v4+ file: one `Default` style, one `Dialogue:` line per cue with
//! times to the centisecond. Braces in the text, which ASS reads as override blocks, are written
//! as the full-width `{` and `}`.
use crate::time::{TICKS_PER_SECOND, Tick};
use crate::{Cue, Document, Error, Result};
const TICKS_PER_CS: i64 = TICKS_PER_SECOND / 100;
/// `H:MM:SS.cc`, the form SSA and ASS use (any number of fraction digits is read).
fn parse_time(s: &str) -> Option<Tick> {
let s = s.trim();
let (hms, frac) = s.split_once('.').unwrap_or((s, ""));
let mut parts = hms.split(':');
let (h, m, sec) = (parts.next()?, parts.next()?, parts.next()?);
if parts.next().is_some() {
return None;
}
let num = |p: &str| -> Option<i64> { (!p.is_empty() && p.len() <= 9 && p.bytes().all(|b| b.is_ascii_digit())).then(|| p.parse().ok()).flatten() };
let (h, m, sec) = (num(h)?, num(m)?, num(sec)?);
if m >= 60 || sec >= 60 || h > 9999 {
return None;
}
let mut ticks = ((h * 60 + m) * 60 + sec) * TICKS_PER_SECOND;
if !frac.is_empty() {
if frac.len() > 9 || !frac.bytes().all(|b| b.is_ascii_digit()) {
return None;
}
let d: i64 = frac.parse().ok()?;
ticks += (i128::from(d) * i128::from(TICKS_PER_SECOND) / 10i128.pow(frac.len() as u32)) as i64;
}
Some(Tick(ticks))
}
fn format_time(t: Tick) -> String {
let cs = (i128::from(t.0.max(0)) + i128::from(TICKS_PER_CS) / 2) / i128::from(TICKS_PER_CS);
let (h, m, s, c) = (cs / 360_000, (cs / 6000) % 60, (cs / 100) % 60, cs % 100);
format!("{h}:{m:02}:{s:02}.{c:02}")
}
/// The Text field of a Dialogue line as cue text; `None` when the line draws shapes.
fn convert_text(raw: &str) -> Option<String> {
let mut out = String::new();
// Open `<i>`, `<b>`, `<u>` in the order they were opened.
let mut open: Vec<char> = Vec::new();
let mut chars = raw.chars().peekable();
let mut drawing = false;
let mut dropped_drawing = false;
while let Some(c) = chars.next() {
match c {
'{' => {
let mut block = String::new();
let mut closed = false;
for b in chars.by_ref() {
if b == '}' {
closed = true;
break;
}
block.push(b);
}
if !closed {
// An unterminated block is literal text.
out.push('{');
out.push_str(&block);
continue;
}
for tag in block.split('\\').skip(1) {
let tag = tag.trim_end();
let (name, val) = tag.split_at(tag.find(|c: char| !c.is_ascii_alphabetic()).unwrap_or(tag.len()));
match name {
"i" | "b" | "u" => {
let letter = name.chars().next().unwrap_or('i');
let on = val.trim() != "0";
if on && !open.contains(&letter) {
open.push(letter);
out.push_str(&format!("<{letter}>"));
} else if !on && open.contains(&letter) {
// Close back to it, reopening what was opened after.
let at = open.iter().position(|&o| o == letter).unwrap_or(0);
let after: Vec<char> = open.split_off(at + 1);
for o in after.iter().rev() {
out.push_str(&format!("</{o}>"));
}
open.pop();
out.push_str(&format!("</{letter}>"));
for o in after {
open.push(o);
out.push_str(&format!("<{o}>"));
}
}
}
"p" => drawing = val.trim().parse::<u32>().unwrap_or(0) != 0,
_ => {}
}
}
}
'\\' => match chars.peek() {
Some('N') => {
chars.next();
out.push('\n');
}
Some('n') => {
chars.next();
out.push(' ');
}
Some('h') => {
chars.next();
out.push('\u{a0}');
}
_ => out.push('\\'),
},
c => {
if drawing {
dropped_drawing = true;
} else {
out.push(c);
}
}
}
}
if dropped_drawing && out.trim().is_empty() {
return None;
}
while let Some(o) = open.pop() {
out.push_str(&format!("</{o}>"));
}
Some(out)
}
pub fn parse(text: &str) -> Result<Document> {
let text = text.strip_prefix('\u{feff}').unwrap_or(text);
let mut doc = Document::default();
let mut in_events = false;
let mut saw_events = false;
// Column of each field in a Dialogue line.
let mut cols: Vec<String> =
["layer", "start", "end", "style", "name", "marginl", "marginr", "marginv", "effect", "text"].map(String::from).to_vec();
let mut drawings = 0usize;
for (n, line) in text.lines().enumerate() {
let line = line.trim();
if line.starts_with('[') && line.ends_with(']') {
in_events = line.eq_ignore_ascii_case("[events]");
saw_events |= in_events;
continue;
}
if !in_events {
continue;
}
let Some((key, rest)) = line.split_once(':') else { continue };
let rest = rest.trim_start();
match key.trim().to_ascii_lowercase().as_str() {
"format" => cols = rest.split(',').map(|f| f.trim().to_ascii_lowercase()).collect(),
"dialogue" => {
// The last column (Text) keeps its commas.
let fields: Vec<&str> = rest.splitn(cols.len(), ',').collect();
let get = |name: &str| cols.iter().position(|c| c == name).and_then(|i| fields.get(i)).copied();
let (Some(start), Some(end), Some(raw)) = (get("start").and_then(parse_time), get("end").and_then(parse_time), get("text")) else {
doc.warnings.push(format!("line {}: not a Dialogue line this reader understands", n + 1));
continue;
};
let Some(text) = convert_text(raw) else {
drawings += 1;
continue;
};
let name = get("name").map(str::trim).filter(|s| !s.is_empty());
doc.cues.push(Cue { start, end, text, speaker: name.map(str::to_string), ..Default::default() });
}
_ => {}
}
}
if !saw_events {
return Err(Error::NotFormat("ASS"));
}
if drawings > 0 {
doc.warnings.push(format!("{drawings} vector drawing line(s) were skipped"));
}
Ok(doc)
}
fn escape(text: &str) -> String {
let mut out = String::with_capacity(text.len() + 8);
let mut rest = text;
while !rest.is_empty() {
if let Some(r) = rest.strip_prefix("\r\n") {
out.push_str("\\N");
rest = r;
} else if let Some(r) = rest.strip_prefix("<i>") {
out.push_str("{\\i1}");
rest = r;
} else if let Some(r) = rest.strip_prefix("</i>") {
out.push_str("{\\i0}");
rest = r;
} else if let Some(r) = rest.strip_prefix("<b>") {
out.push_str("{\\b1}");
rest = r;
} else if let Some(r) = rest.strip_prefix("</b>") {
out.push_str("{\\b0}");
rest = r;
} else if let Some(r) = rest.strip_prefix("<u>") {
out.push_str("{\\u1}");
rest = r;
} else if let Some(r) = rest.strip_prefix("</u>") {
out.push_str("{\\u0}");
rest = r;
} else if let Some(c) = rest.chars().next() {
match c {
'\n' | '\r' => out.push_str("\\N"),
// Empty override block separates a literal slash from N/n/h.
'\\' => out.push_str("\\{}"),
'{' => out.push('\u{ff5b}'),
'}' => out.push('\u{ff5d}'),
'\u{a0}' => out.push_str("\\h"),
c => out.push(c),
}
rest = &rest[c.len_utf8()..];
}
}
out
}
pub fn write(doc: &Document) -> String {
let mut out = String::from(
"[Script Info]\n; Written by craft-captions\nScriptType: v4.00+\nWrapStyle: 0\nScaledBorderAndShadow: yes\nPlayResX: 384\nPlayResY: 288\n\n\
[V4+ Styles]\nFormat: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding\n\
Style: Default,Arial,16,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,1,0,2,10,10,10,1\n\n\
[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\n",
);
for c in &doc.cues {
// A comma in the Name field would shift the columns; the other fields are fixed text.
let name = c.speaker.as_deref().unwrap_or("").replace([',', '\n', '\r'], " ");
out.push_str(&format!("Dialogue: 0,{},{},Default,{},0,0,0,,{}\n", format_time(c.start), format_time(c.end), name, escape(&c.text)));
}
out
}
+14 -3
View File
@@ -4,7 +4,7 @@
//! - **Files:** [SubRip](srt) (`.srt`), [WebVTT](vtt) (`.vtt`), [Scenarist SCC](scc) (`.scc`,
//! CEA-608 pop-on, roll-up and paint-on on read; pop-on on write), [MacCaption MCC](mcc)
//! (`.mcc`, SMPTE ST 334-2 packets with CEA-608 and CEA-708), [EBU STL](stl) (`.stl`, EBU
//! Tech 3264) and [TTML](ttml) (`.ttml` IMSC1 Text profile, `.dfxp` DFXP) parse into a
//! Tech 3264), [ASS/SSA](ass) (`.ass`, `.ssa`) and [TTML](ttml) (`.ttml` IMSC1 Text profile, `.dfxp` DFXP) parse into a
//! [`Document`] of [`Cue`]s and write back. Readers are forgiving (BOM, UTF-16, Windows-1252
//! fallback, CRLF/CR, missing SRT indexes, `,` or `.` milliseconds, missing hours, no blank
//! line between cues); writers are strict. WebVTT cue identifiers, cue settings, `<v Speaker>`
@@ -32,6 +32,7 @@
#[doc = include_str!("../README.md")]
struct ReadmeExamples;
pub mod ass;
pub mod cea608;
pub mod mcc;
pub mod scc;
@@ -69,10 +70,12 @@ pub enum Format {
Ttml,
/// DFXP (TTML1).
Dfxp,
/// Advanced SubStation Alpha (also reads SubStation Alpha).
Ass,
}
impl Format {
pub const ALL: [Format; 7] = [Format::Srt, Format::WebVtt, Format::Scc, Format::Mcc, Format::Stl, Format::Ttml, Format::Dfxp];
pub const ALL: [Format; 8] = [Format::Srt, Format::WebVtt, Format::Scc, Format::Mcc, Format::Stl, Format::Ttml, Format::Dfxp, Format::Ass];
pub fn name(self) -> &'static str {
match self {
Format::Srt => "SubRip (SRT)",
@@ -82,6 +85,7 @@ impl Format {
Format::Stl => "EBU STL",
Format::Ttml => "TTML (IMSC1)",
Format::Dfxp => "DFXP (TTML1)",
Format::Ass => "Advanced SubStation Alpha (ASS)",
}
}
pub fn extension(self) -> &'static str {
@@ -93,6 +97,7 @@ impl Format {
Format::Stl => "stl",
Format::Ttml => "ttml",
Format::Dfxp => "dfxp",
Format::Ass => "ass",
}
}
pub fn from_name(s: &str) -> Option<Format> {
@@ -104,6 +109,7 @@ impl Format {
"stl" | "ebu-stl" | "ebustl" | "ebu" => Some(Format::Stl),
"ttml" | "imsc" | "imsc1" | "xml" => Some(Format::Ttml),
"dfxp" => Some(Format::Dfxp),
"ass" | "ssa" => Some(Format::Ass),
_ => None,
}
}
@@ -251,6 +257,9 @@ pub fn detect(bytes: &[u8], ext: Option<&str>) -> Option<Format> {
if head.starts_with("File Format=MacCaption_MCC") {
return Some(Format::Mcc);
}
if head.starts_with("[Script Info]") {
return Some(Format::Ass);
}
let ext = ext.map(|e| e.trim_start_matches('.').to_ascii_lowercase());
if (head.starts_with('<') && (head.contains("<tt ") || head.contains("<tt>") || head.contains(":tt ")))
&& (head.contains("ns/ttml") || head.contains("ttaf1"))
@@ -262,7 +271,7 @@ pub fn detect(bytes: &[u8], ext: Option<&str>) -> Option<Format> {
match ext.as_deref() {
Some("srt") if has_arrow_timing || head.is_empty() => Some(Format::Srt),
Some("vtt") if has_arrow_timing => Some(Format::WebVtt),
Some("srt" | "vtt" | "scc" | "mcc" | "stl" | "ttml" | "dfxp" | "xml") => None,
Some("srt" | "vtt" | "scc" | "mcc" | "stl" | "ttml" | "dfxp" | "xml" | "ass" | "ssa") => None,
_ if has_arrow_timing => Some(Format::Srt),
_ => None,
}
@@ -296,6 +305,7 @@ fn parse_unbounded(bytes: &[u8], format: Format) -> Result<Document> {
Format::Scc => scc::parse(&text),
Format::Mcc => mcc::parse(&text),
Format::Ttml | Format::Dfxp => ttml::parse(&text),
Format::Ass => ass::parse(&text),
Format::Stl => stl::parse(bytes),
}
}
@@ -333,6 +343,7 @@ pub fn write(doc: &Document, format: Format, opts: WriteOptions) -> Vec<u8> {
Format::Stl => stl::write(doc, opts.rate, opts.program),
Format::Ttml => ttml::write(doc, ttml::Flavor::Imsc1, opts.rate, doc.language.as_deref().unwrap_or("")).into_bytes(),
Format::Dfxp => ttml::write(doc, ttml::Flavor::Dfxp, opts.rate, doc.language.as_deref().unwrap_or("")).into_bytes(),
Format::Ass => ass::write(doc).into_bytes(),
}
}
+142
View File
@@ -0,0 +1,142 @@
//! SubStation Alpha / Advanced SubStation Alpha: reading, writing, and ffmpeg as the reference
//! (oracle; skipped when ffmpeg is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`).
use craft_captions::{Cue, Document, Format, Tick, WriteOptions, detect, parse, write};
use std::process::Command;
const T: i64 = craft_captions::TICKS_PER_SECOND;
fn cs(n: i64) -> Tick {
Tick(n * (T / 100))
}
const SAMPLE: &str = "\u{feff}[Script Info]\n; a comment\nTitle: Test\nScriptType: v4.00+\n\n[V4+ Styles]\nFormat: Name, Fontname\nStyle: Default,Arial\n\n[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\nComment: 0,0:00:00.00,0:00:01.00,Default,,0,0,0,,not a cue\nDialogue: 0,0:00:01.50,0:00:03.25,Default,Bob,0,0,0,,Hello, {\\i1}world{\\i0}\\Nsecond {\\b1}line{\\b0}\nDialogue: 0,1:02:03.04,1:02:04.5,Default,,0,0,0,,{\\pos(10,20)\\c&H0000FF&}Red\\hspace\\nsoft\nDialogue: 0,0:00:09.00,0:00:10.00,Default,,0,0,0,,{\\p1}m 0 0 l 100 0 100 100{\\p0}\n";
#[test]
fn reads_dialogue_lines_with_commas_overrides_and_line_breaks() {
let doc = parse(SAMPLE.as_bytes(), Format::Ass).unwrap();
assert_eq!(doc.cues.len(), 2);
assert_eq!(doc.cues[0].start, cs(150));
assert_eq!(doc.cues[0].end, cs(325));
assert_eq!(doc.cues[0].text, "Hello, <i>world</i>\nsecond <b>line</b>");
assert_eq!(doc.cues[0].speaker.as_deref(), Some("Bob"));
// 1:02:03.04, a one-digit fraction, an override block dropped, \h and \n.
assert_eq!(doc.cues[1].start, Tick((3600 + 120 + 3) * T + 4 * (T / 100)));
assert_eq!(doc.cues[1].end, Tick((3600 + 120 + 4) * T + T / 2));
assert_eq!(doc.cues[1].text, "Red\u{a0}space soft");
assert!(doc.warnings.iter().any(|w| w.contains("vector drawing")), "{:?}", doc.warnings);
}
#[test]
fn ssa_v4_files_read_through_their_own_format_line() {
let ssa = "[Script Info]\nScriptType: v4.00\n\n[V4 Styles]\nFormat: Name\n\n[Events]\nFormat: Marked, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\nDialogue: Marked=0,0:00:01.00,0:00:02.00,*Default,,0000,0000,0000,,Old style\n";
let doc = parse(ssa.as_bytes(), Format::Ass).unwrap();
assert_eq!((doc.cues[0].start, doc.cues[0].end, doc.cues[0].text.as_str()), (cs(100), cs(200), "Old style"));
}
#[test]
fn write_then_read_keeps_times_text_and_speaker() {
let cues = vec![
Cue { start: cs(100), end: cs(250), text: "Line one\n<i>line two</i>".into(), speaker: Some("Ann".into()), ..Default::default() },
Cue {
start: Tick(7200 * T + 99 * (T / 100)),
end: Tick(7203 * T),
text: "<b>bold</b> and <u>under</u> {braces}".into(),
..Default::default()
},
];
let doc = Document { cues, ..Default::default() };
let bytes = write(&doc, Format::Ass, WriteOptions::default());
assert_eq!(detect(&bytes, Some("ass")), Some(Format::Ass));
let back = parse(&bytes, Format::Ass).unwrap();
assert_eq!(back.cues[0], doc.cues[0]);
assert_eq!(back.cues[1].start, doc.cues[1].start);
// Braces are written full-width, as ASS reads `{` as the start of an override block.
assert_eq!(back.cues[1].text, "<b>bold</b> and <u>under</u> \u{ff5b}braces\u{ff5d}");
}
#[test]
fn files_without_an_events_section_are_not_ass() {
assert!(parse(b"[Script Info]\nTitle: x\n", Format::Ass).is_err());
assert!(parse(b"hello", Format::Ass).is_err());
assert_eq!(detect(b"hello", Some("ass")), None);
}
#[test]
fn bad_lines_are_skipped_with_a_warning() {
let text = "[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\nDialogue: 0,garbage,0:00:02.00,Default,,0,0,0,,x\nDialogue: 0,0:00:01.00,0:00:02.00,Default,,0,0,0,,ok\n";
let doc = parse(text.as_bytes(), Format::Ass).unwrap();
assert_eq!(doc.cues.len(), 1);
assert_eq!(doc.warnings.len(), 1);
}
fn ffmpeg_run(ff: &std::path::Path, args: &[&str]) {
let out = Command::new(ff).args(["-v", "error", "-nostdin", "-y"]).args(args).output().expect("run ffmpeg");
assert!(out.status.success(), "ffmpeg {args:?}: {}", String::from_utf8_lossy(&out.stderr));
}
const SRT: &str = "1\n00:00:01,500 --> 00:00:03,250\nHello, <i>world</i>\nsecond <b>line</b>\n\n2\n00:00:04,000 --> 00:00:05,990\nPlain, with a comma\n\n3\n01:00:00,010 --> 01:00:02,999\n<u>Under</u> and <i>italic <b>both</b></i>\n";
#[test]
fn we_read_what_ffmpeg_writes() {
let Some(ff) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("captions_ass");
let (srt, ass) = (dir.join("in.srt"), dir.join("ffmpeg.ass"));
std::fs::write(&srt, SRT).expect("write");
ffmpeg_run(&ff, &["-i", srt.to_str().expect("path"), ass.to_str().expect("path")]);
let from_ass = parse(&std::fs::read(&ass).expect("read"), Format::Ass).expect("parse ass");
let from_srt = parse(SRT.as_bytes(), Format::Srt).expect("parse srt");
assert_eq!(from_ass.cues.len(), from_srt.cues.len());
for (a, s) in from_ass.cues.iter().zip(&from_srt.cues) {
// ASS times are centiseconds; the SRT ones round to them.
assert_eq!(a.start, cs((s.start.0 + T / 200) / (T / 100)), "start of {:?}", s.text);
assert_eq!(a.end, cs((s.end.0 + T / 200) / (T / 100)), "end of {:?}", s.text);
assert_eq!(a.text, s.text);
}
}
#[test]
fn ffmpeg_reads_what_we_write() {
let Some(ff) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("captions_ass");
let mut doc = parse(SRT.as_bytes(), Format::Srt).expect("parse srt");
doc.cues.push(Cue { start: cs(400_000), end: cs(400_100), text: r"C:\New\notes\hello and \N \n \h".into(), ..Default::default() });
let (ass, srt) = (dir.join("ours.ass"), dir.join("back.srt"));
std::fs::write(&ass, write(&doc, Format::Ass, WriteOptions::default())).expect("write");
ffmpeg_run(&ff, &["-i", ass.to_str().expect("path"), srt.to_str().expect("path")]);
let theirs = parse(&std::fs::read(&srt).expect("read"), Format::Srt).expect("parse back");
assert_eq!(theirs.cues.len(), doc.cues.len());
for (t, d) in theirs.cues.iter().zip(&doc.cues) {
assert_eq!(t.start, cs((d.start.0 + T / 200) / (T / 100)));
assert_eq!(t.end, cs((d.end.0 + T / 200) / (T / 100)));
assert_eq!(t.text, d.text, "text of the cue at {:?}", d.start);
}
}
#[test]
fn literal_backslashes_survive_ass_round_trip() {
let text = r"C:\New\notes\hello and \N \n \h";
let doc = Document { cues: vec![Cue { start: cs(100), end: cs(200), text: text.into(), ..Default::default() }], ..Default::default() };
let bytes = write(&doc, Format::Ass, WriteOptions::default());
assert_eq!(parse(&bytes, Format::Ass).unwrap().cues[0].text, text);
}
#[test]
fn carriage_returns_cannot_create_dialogue_records() {
let doc = Document {
cues: vec![Cue {
start: cs(100),
end: cs(200),
text: "first\rsecond\r\nthird".into(),
speaker: Some("Ann\rOther".into()),
..Default::default()
}],
..Default::default()
};
let bytes = write(&doc, Format::Ass, WriteOptions::default());
assert!(!bytes.contains(&b'\r'));
let back = parse(&bytes, Format::Ass).unwrap();
assert_eq!(back.cues.len(), 1);
assert_eq!(back.cues[0].text, "first\nsecond\nthird");
assert_eq!(back.cues[0].speaker.as_deref(), Some("Ann Other"));
}
+1
View File
@@ -1,3 +1,4 @@
mod ass;
mod limits;
mod literal_roundtrips;
mod mcc_708_timing;
+12
View File
@@ -424,6 +424,18 @@ fn shipped_cmyk(bytes: &[u8], b: Builtin) -> Profile {
})
}
/// Generates the compact ICC v2.1 sRGB matrix/TRC profile used by PDFCraft.
///
/// Unlike [`Builtin::Srgb`]'s v4 profile, this uses a 1024-sample tone curve and
/// v2 `desc`/`text` tags for consumers that require a v2 output intent. The legacy
/// description `sRGB (PdfCraft)` is retained to preserve existing document bytes.
/// The generated profile contains no external assets; callers choose where it is
/// appropriate (including their own PDF/A conformance policy).
/// All sizes are fixed; no input-controlled allocation or recursion is involved.
pub fn srgb_v2() -> Vec<u8> {
crate::builtin_v2::srgb()
}
#[cfg(test)]
mod tests {
use super::*;
+143
View File
@@ -0,0 +1,143 @@
//! A small sRGB ICC profile (version 2, display class, matrix/TRC), written from the published
//! sRGB primaries (IEC 61966-2-1) adapted to D50, with the sRGB tone curve sampled at 1024
//! points. Used as the PDF/A output intent's destination profile.
fn s15f16(v: f64) -> [u8; 4] {
((v * 65536.0).round() as i32).to_be_bytes()
}
fn xyz(x: f64, y: f64, z: f64) -> Vec<u8> {
let mut t = b"XYZ \0\0\0\0".to_vec();
t.extend(s15f16(x));
t.extend(s15f16(y));
t.extend(s15f16(z));
t
}
fn desc(text: &str) -> Vec<u8> {
let mut t = b"desc\0\0\0\0".to_vec();
let ascii: Vec<u8> = text.bytes().chain(std::iter::once(0)).collect();
t.extend((ascii.len() as u32).to_be_bytes());
t.extend(&ascii);
// No Unicode or ScriptCode descriptions.
t.extend([0u8; 4 + 4]);
t.extend([0u8; 2 + 1 + 67]);
t
}
fn text(text: &str) -> Vec<u8> {
let mut t = b"text\0\0\0\0".to_vec();
t.extend(text.bytes());
t.push(0);
t
}
fn curve() -> Vec<u8> {
const N: usize = 1024;
let mut t = b"curv\0\0\0\0".to_vec();
t.extend((N as u32).to_be_bytes());
for i in 0..N {
let v = i as f64 / (N - 1) as f64;
let lin = if v <= 0.04045 { v / 12.92 } else { ((v + 0.055) / 1.055).powf(2.4) };
t.extend(((lin * 65535.0).round() as u16).to_be_bytes());
}
t
}
/// Fixed-size profile bytes; all tag sizes and loop counts are constants.
pub fn srgb() -> Vec<u8> {
// sRGB primaries, Bradford-adapted to the D50 profile connection space.
let tags: Vec<(&[u8; 4], Vec<u8>)> = vec![
(b"desc", desc("sRGB (PdfCraft)")),
(b"cprt", text("No copyright, use freely")),
(b"wtpt", xyz(0.9642, 1.0, 0.8249)),
(b"rXYZ", xyz(0.4361, 0.2225, 0.0139)),
(b"gXYZ", xyz(0.3851, 0.7169, 0.0971)),
(b"bXYZ", xyz(0.1431, 0.0606, 0.7141)),
(b"rTRC", curve()),
];
// gTRC and bTRC share rTRC's data.
let count = tags.len() + 2;
let table_len = 4 + count * 12;
let mut offset = 128 + table_len;
let mut table = (count as u32).to_be_bytes().to_vec();
let mut data = Vec::new();
let mut trc = (0, 0);
for (sig, body) in &tags {
let len = body.len();
table.extend(*sig);
table.extend((offset as u32).to_be_bytes());
table.extend((len as u32).to_be_bytes());
if *sig == b"rTRC" {
trc = (offset, len);
}
data.extend(body);
// Tags start on 4-byte boundaries.
let pad = (4 - len % 4) % 4;
data.extend(std::iter::repeat_n(0u8, pad));
offset += len + pad;
}
for sig in [b"gTRC", b"bTRC"] {
table.extend(sig);
table.extend((trc.0 as u32).to_be_bytes());
table.extend((trc.1 as u32).to_be_bytes());
}
let size = 128 + table.len() + data.len();
let mut h = Vec::with_capacity(size);
h.extend((size as u32).to_be_bytes());
h.extend(b"\0\0\0\0"); // preferred CMM
h.extend([2, 0x10, 0, 0]); // version 2.1
h.extend(b"mntr");
h.extend(b"RGB ");
h.extend(b"XYZ ");
h.extend([0u8; 12]); // date
h.extend(b"acsp");
h.extend(b"\0\0\0\0"); // platform
h.extend([0u8; 4]); // flags
h.extend([0u8; 4]); // manufacturer
h.extend([0u8; 4]); // model
h.extend([0u8; 8]); // attributes
h.extend([0, 0, 0, 0]); // perceptual intent
h.extend(s15f16(0.9642));
h.extend(s15f16(1.0));
h.extend(s15f16(0.8249));
h.extend([0u8; 4]); // creator
h.resize(128, 0);
h.extend(table);
h.extend(data);
h
}
#[cfg(test)]
mod tests {
#[test]
fn parses_as_v2_with_shared_rgb_curves() {
let bytes = super::srgb();
let p = crate::Profile::parse(&bytes).unwrap();
assert_eq!(p.version, (2, 0x10));
assert_eq!(p.color_space, crate::ColorSpace::Rgb);
assert_eq!(p.pcs, crate::Pcs::Xyz);
assert_eq!(p.description, "sRGB (PdfCraft)");
let curves = p.trc.unwrap();
assert_eq!(curves[0], curves[1]);
assert_eq!(curves[1], curves[2]);
assert!(matches!(&curves[0], crate::Curve::Table(v) if v.len() == 1024 && v[0] == 0.0 && v[1023] == 1.0));
assert_eq!(bytes, super::srgb());
}
#[test]
fn profile_is_well_formed() {
let p = super::srgb();
assert_eq!(u32::from_be_bytes(p[0..4].try_into().unwrap()) as usize, p.len());
assert_eq!(&p[36..40], b"acsp");
assert_eq!(&p[12..20], b"mntrRGB ");
let n = u32::from_be_bytes(p[128..132].try_into().unwrap()) as usize;
assert_eq!(n, 9);
for i in 0..n {
let e = 132 + i * 12;
let off = u32::from_be_bytes(p[e + 4..e + 8].try_into().unwrap()) as usize;
let len = u32::from_be_bytes(p[e + 8..e + 12].try_into().unwrap()) as usize;
assert!(off.is_multiple_of(4) && off + len <= p.len(), "tag {i}");
}
}
}
+2
View File
@@ -20,6 +20,7 @@
#![forbid(unsafe_code)]
pub mod builtin;
mod builtin_v2;
pub mod clut;
pub mod curve;
pub mod gamut;
@@ -33,6 +34,7 @@ pub mod profile;
pub mod synth;
pub mod transform;
mod write;
pub mod write_v2;
pub use builtin::Builtin;
pub use clut::Clut;
+47 -7
View File
@@ -531,8 +531,7 @@ pub fn write_cube(l: &LutFile) -> String {
s.push_str(&format!("DOMAIN_MAX {} {} {}\n", l.domain_max[0], l.domain_max[1], l.domain_max[2]));
}
s.push_str(&format!("LUT_3D_SIZE {}\n", l.size));
write_cube_rows(&mut s, l);
s
cube_rows(s, l.data.as_chunks::<3>().0.iter().copied())
}
/// Writes a `.cube` file with a creator comment, section comments and an explicit input domain.
@@ -549,14 +548,33 @@ pub fn write_cube_commented(l: &LutFile, creator: &str) -> String {
s.push_str(&format!("DOMAIN_MAX {} {} {}\n", l.domain_max[0], l.domain_max[1], l.domain_max[2]));
}
s.push_str("\n#LUT data points\n");
write_cube_rows(&mut s, l);
cube_rows(s, l.data.as_chunks::<3>().0.iter().copied())
}
fn cube_rows(mut s: String, rows: impl Iterator<Item = [f32; 3]>) -> String {
for c in rows {
s.push_str(&format!("{:.6} {:.6} {:.6}\n", c[0], c[1], c[2]));
}
s
}
fn write_cube_rows(s: &mut String, l: &LutFile) {
for c in l.data.as_chunks::<3>().0 {
s.push_str(&format!("{:.6} {:.6} {:.6}\n", c[0], c[1], c[2]));
}
/// Annotated identity-domain CUBE export, streamed in red-fastest order without a table copy.
/// Callers supply exactly `size³` rows for a valid size (2..=[`MAX_SIZE`]), as with [`write_cube`].
/// Integer-depth exports clamp/round to 1/32768 steps; floating exports clamp without rounding.
pub fn write_cube_export(creator: &str, title: &str, size: usize, integer_depth: bool, rows: impl Iterator<Item = [f32; 3]>) -> String {
let s = format!(
"#Created by: {creator}\nTITLE \"{}\"\n\n#LUT size\nLUT_3D_SIZE {size}\n\n#data domain\nDOMAIN_MIN 0.0 0.0 0.0\nDOMAIN_MAX 1.0 1.0 1.0\n\n#LUT data points\n",
title.replace('"', "'")
);
cube_rows(
s,
rows.map(|c| {
c.map(|v| {
let v = v.clamp(0.0, 1.0);
if integer_depth { (v * 32768.0).round() / 32768.0 } else { v }
})
}),
)
}
fn luma(c: [f32; 3]) -> f32 {
@@ -1345,4 +1363,26 @@ LUT_3D_SIZE 2
assert_eq!(back.domain_min, l.domain_min, "the written table must mean the same");
assert_eq!(back.domain_max, l.domain_max);
}
#[test]
fn annotated_cube_export_preserves_header_and_integer_precision() {
let mut lut = LutFile::identity(2).unwrap();
lut.title = "My \"Look\"".into();
lut.data[..3].copy_from_slice(&[1.0 / 6.0, 5.0 / 6.0, 160.0 / 255.0]);
let output = write_cube_export("PhotoCraft", &lut.title, lut.size, true, lut.data.as_chunks::<3>().0.iter().copied());
assert!(output.starts_with("#Created by: PhotoCraft\nTITLE \"My 'Look'\"\n\n#LUT size\nLUT_3D_SIZE 2\n\n#data domain\nDOMAIN_MIN 0.0 0.0 0.0\nDOMAIN_MAX 1.0 1.0 1.0\n\n#LUT data points\n0.166656 0.833344 0.627441\n"));
assert_eq!(output.lines().count(), 11 + 8);
let parsed = parse_cube(&output).unwrap();
assert_eq!(parsed.size, 2);
assert_eq!(&parsed.data[3..], &lut.data[3..]);
let float = write_cube_export("PhotoCraft", &lut.title, lut.size, false, lut.data.as_chunks::<3>().0.iter().copied());
assert!(float.contains("0.166667 0.833333 0.627451\n"));
}
#[test]
fn annotated_empty_title_and_float_clamping() {
let text = write_cube_export("Exporter", "", 2, false, std::iter::repeat_n([-0.5, 0.25, 1.5], 8));
assert!(text.contains("TITLE \"\"\n"));
let back = parse_cube(&text).unwrap();
assert_eq!(back.data, [0.0, 0.25, 1.0].repeat(8));
}
}
+195
View File
@@ -0,0 +1,195 @@
//! Bounded ICC v2.1 matrix/TRC display-profile writer, extracted from TextureCraft.
//! Colour-space selection and transfer-curve sampling remain caller policy.
const D50_XYZ: [f64; 3] = [0.9642, 1.0, 0.8249];
/// One common red/green/blue transfer curve.
#[derive(Clone, Copy)]
pub enum ToneCurve<'a> {
/// ICC gamma 1.0 (`curv` with one u8Fixed8 entry).
Linear,
/// Already quantized samples, inclusive endpoints, between 2 and 4096 entries.
Samples(&'a [u16]),
}
/// Parameters for an ICC v2.1 RGB display profile.
pub struct MatrixProfile<'a> {
/// RGB-to-XYZ matrix already adapted to PCS D50, in row-major order.
pub matrix: [[f64; 3]; 3],
/// Common RGB transfer curve; its storage is shared by all three tags.
pub curve: ToneCurve<'a>,
/// ASCII description, at most 1024 bytes with no embedded NUL.
pub description: &'a str,
/// ASCII copyright text, at most 1024 bytes with no embedded NUL.
pub copyright: &'a str,
/// Raw ICC date fields: year, month, day, hour, minute, second.
pub date: [u16; 6],
}
fn s15f16(v: f64) -> [u8; 4] {
((v * 65536.0).round().clamp(f64::from(i32::MIN), f64::from(i32::MAX)) as i32).to_be_bytes()
}
fn xyz_tag(v: [f64; 3]) -> Vec<u8> {
let mut b = b"XYZ \0\0\0\0".to_vec();
for c in v {
b.extend_from_slice(&s15f16(c));
}
b
}
fn text_tag(text: &str) -> Vec<u8> {
let mut b = b"text\0\0\0\0".to_vec();
b.extend_from_slice(text.as_bytes());
b.push(0);
b
}
/// `textDescriptionType` with the ASCII description only.
fn desc_tag(text: &str) -> Vec<u8> {
let mut b = b"desc\0\0\0\0".to_vec();
b.extend_from_slice(&(text.len() as u32 + 1).to_be_bytes());
b.extend_from_slice(text.as_bytes());
b.push(0);
// No Unicode text and no Macintosh ScriptCode text: empty fields and the 67-byte filler.
b.extend_from_slice(&[0; 4 + 4 + 2 + 1 + 67]);
b
}
fn curve_tag(curve: ToneCurve<'_>) -> Vec<u8> {
let mut b = b"curv\0\0\0\0".to_vec();
match curve {
ToneCurve::Linear => {
b.extend_from_slice(&1u32.to_be_bytes());
b.extend_from_slice(&0x0100u16.to_be_bytes());
}
ToneCurve::Samples(samples) => {
b.extend_from_slice(&(samples.len() as u32).to_be_bytes());
for sample in samples {
b.extend_from_slice(&sample.to_be_bytes());
}
}
}
b
}
/// Write a deterministic ICC v2.1 RGB display profile with one shared RGB TRC.
///
/// Returns `None` for nonfinite matrix values, descriptions longer than 1024 ASCII
/// bytes or containing NUL, or sampled curves outside 2..=4096 entries. These caps
/// bound every allocation independently of caller input. Matrix values outside the
/// signed 15.16 range saturate, matching the legacy exporter. The caller owns colour
/// adaptation, transfer sampling, names and timestamp policy.
pub fn matrix_profile(params: &MatrixProfile<'_>) -> Option<Vec<u8>> {
let valid_text = |s: &str| s.len() <= 1024 && s.is_ascii() && !s.contains('\0');
if !valid_text(params.description)
|| !valid_text(params.copyright)
|| !params.matrix.iter().flatten().all(|v| v.is_finite())
|| matches!(params.curve, ToneCurve::Samples(s) if !(2..=4096).contains(&s.len()))
{
return None;
}
let m = params.matrix;
let column = |c: usize| [m[0][c], m[1][c], m[2][c]];
let curve = curve_tag(params.curve);
// The green and blue curves are the red one's entry.
let tags: [(&[u8; 4], Vec<u8>); 9] = [
(b"desc", desc_tag(params.description)),
(b"cprt", text_tag(params.copyright)),
(b"wtpt", xyz_tag(D50_XYZ)),
(b"rXYZ", xyz_tag(column(0))),
(b"gXYZ", xyz_tag(column(1))),
(b"bXYZ", xyz_tag(column(2))),
(b"rTRC", curve.clone()),
(b"gTRC", curve.clone()),
(b"bTRC", curve),
];
// Header (128) + tag count (4) + 12 per tag, then the tag data, each tag padded to 4 bytes.
let table_end = 128 + 4 + 12 * tags.len();
let mut offsets = Vec::new();
let mut data: Vec<u8> = Vec::new();
for (i, (_, bytes)) in tags.iter().enumerate() {
let shared = i >= 7;
let at = if shared { offsets.get(6).copied().unwrap_or(0) } else { table_end + data.len() };
offsets.push(at);
if !shared {
data.extend_from_slice(bytes);
while !data.len().is_multiple_of(4) {
data.push(0);
}
}
}
let total = table_end + data.len();
let mut out = vec![0u8; 128];
out.get_mut(0..4)?.copy_from_slice(&(total as u32).to_be_bytes());
out.get_mut(8..12)?.copy_from_slice(&[2, 0x10, 0, 0]); // version 2.1.0
out.get_mut(12..16)?.copy_from_slice(b"mntr");
out.get_mut(16..20)?.copy_from_slice(b"RGB ");
out.get_mut(20..24)?.copy_from_slice(b"XYZ ");
// Serialize caller-supplied ICC date fields; no calendar arithmetic.
for (i, value) in params.date.iter().enumerate() {
out.get_mut(24 + i * 2..26 + i * 2)?.copy_from_slice(&value.to_be_bytes());
}
out.get_mut(36..40)?.copy_from_slice(b"acsp");
for (k, v) in D50_XYZ.iter().enumerate() {
out.get_mut(68 + 4 * k..72 + 4 * k)?.copy_from_slice(&s15f16(*v));
}
out.extend_from_slice(&(tags.len() as u32).to_be_bytes());
for ((sig, bytes), at) in tags.iter().zip(&offsets) {
out.extend_from_slice(*sig);
out.extend_from_slice(&(*at as u32).to_be_bytes());
out.extend_from_slice(&(bytes.len() as u32).to_be_bytes());
}
out.extend_from_slice(&data);
Some(out)
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used)]
use super::*;
fn params() -> MatrixProfile<'static> {
MatrixProfile {
matrix: [[0.4361, 0.3851, 0.1431], [0.2225, 0.7169, 0.0606], [0.0139, 0.0971, 0.7141]],
curve: ToneCurve::Linear,
description: "v2",
copyright: "free",
date: [2026, 1, 1, 0, 0, 0],
}
}
#[test]
fn valid_profile_parses_and_aliases_curves() {
for curve in [ToneCurve::Linear, ToneCurve::Samples(&[0, 32768, 65535])] {
let bytes = matrix_profile(&MatrixProfile { curve, ..params() }).unwrap();
let p = crate::Profile::parse(&bytes).unwrap();
assert_eq!(p.version, (2, 0x10));
assert_eq!(p.description, "v2");
assert_eq!(&bytes[24..28], &[7, 234, 0, 1]);
assert_eq!(&bytes[208..216], &bytes[220..228]);
assert_eq!(&bytes[208..216], &bytes[232..240]);
assert_eq!(bytes, matrix_profile(&MatrixProfile { curve, ..params() }).unwrap());
}
}
#[test]
fn bounded_inputs_reject_before_serializing() {
let long = "x".repeat(1025);
for description in [long.as_str(), "bad\0name", "non-ascii é"] {
assert!(matrix_profile(&MatrixProfile { description, ..params() }).is_none());
}
for samples in [&[][..], &[0][..], &vec![0; 4097][..]] {
assert!(matrix_profile(&MatrixProfile { curve: ToneCurve::Samples(samples), ..params() }).is_none());
}
for value in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
let mut p = params();
p.matrix[0][0] = value;
assert!(matrix_profile(&p).is_none());
}
let samples = vec![0; 4096];
let name = "x".repeat(1024);
let bytes = matrix_profile(&MatrixProfile { description: &name, copyright: &name, curve: ToneCurve::Samples(&samples), ..params() }).unwrap();
assert!(bytes.len() < 12 * 1024);
}
}
+55 -24
View File
@@ -62,6 +62,10 @@ impl Limits {
/// A byte count in megabytes for messages ("9.9 MB", "1024 MB").
#[cfg_attr(no_dwg_bridge, allow(dead_code))]
#[expect(
clippy::cast_precision_loss,
reason = "Megabyte formatting is rounded for display; exact integer precision beyond 2^53 bytes is not meaningful."
)]
fn mb(n: u64) -> String {
let m = n as f64 / f64::from(1u32 << 20);
if m >= 100.0 { format!("{m:.0} MB") } else { format!("{m:.1} MB") }
@@ -79,12 +83,17 @@ mod proxy_transport;
#[cfg(not(no_dwg_bridge))]
mod native {
use std::fmt::Write as _;
use std::io::{Cursor, Write};
use std::panic::AssertUnwindSafe;
use super::{Limits, mb};
/// Read DWG bytes and return an ASCII DXF rendition, within [`Limits::DEFAULT`].
///
/// # Errors
///
/// Returns an error when the DWG cannot be read or post-processed, or its DXF rendition exceeds the default limits.
pub fn dwg_to_dxf(bytes: &[u8]) -> Result<Vec<u8>, String> {
dwg_to_dxf_with(bytes, Limits::DEFAULT)
}
@@ -92,6 +101,10 @@ mod native {
/// [`dwg_to_dxf`] with explicit limits. Both are checked before the expensive step they
/// guard: the input size before the DWG reader runs, the DXF size while it is written, so a
/// runaway conversion stops at the limit instead of filling memory first.
///
/// # Errors
///
/// Returns an error when the input exceeds `limits`, decoding fails, or the DXF output exceeds `limits`.
pub fn dwg_to_dxf_with(bytes: &[u8], limits: Limits) -> Result<Vec<u8>, String> {
dwg_to_dxf_noted(bytes, limits).map(|(dxf, _)| dxf)
}
@@ -100,6 +113,10 @@ mod native {
/// failsafe mode: an object record it can't decode is skipped instead of failing the whole
/// file, and the notes say how many were skipped and of which types, so a partial read never
/// passes for a complete one.
///
/// # Errors
///
/// Returns an error when the input exceeds `limits`, decoding fails, or the DXF output exceeds `limits`.
pub fn dwg_to_dxf_noted(bytes: &[u8], limits: Limits) -> Result<(Vec<u8>, Vec<String>), String> {
if bytes.len() > limits.max_dwg_bytes {
return Err(format!(
@@ -122,13 +139,13 @@ mod native {
let mut notes = read_notes(&outcome.stats);
let mut doc = outcome.document;
notes.extend(
guarded(AssertUnwindSafe(|| application_objects(&mut doc))).map_err(|_| "the DWG application object conversion failed".to_string())?,
guarded(AssertUnwindSafe(|| application_objects(&mut doc))).map_err(|()| "the DWG application object conversion failed".to_string())?,
);
// After application_objects, so the proxy objects it makes are numbered as the DXF's.
notes.extend(
guarded(AssertUnwindSafe(|| super::proxy_transport::prepare(&mut doc))).map_err(|_| "the DWG proxy conversion failed".to_string())?,
guarded(AssertUnwindSafe(|| super::proxy_transport::prepare(&mut doc))).map_err(|()| "the DWG proxy conversion failed".to_string())?,
);
let orphans = guarded(AssertUnwindSafe(|| post_process(&mut doc))).map_err(|_| "the DWG post-processing failed on this file".to_string())?;
let orphans = guarded(AssertUnwindSafe(|| post_process(&mut doc))).map_err(|()| "the DWG post-processing failed on this file".to_string())?;
if orphans > 0 {
let (s, were) = if orphans == 1 { ("", "was") } else { ("s", "were") };
notes.push(format!("DWG: {orphans} DGN line style component{s} that no line style definition uses {were} left out"));
@@ -632,7 +649,7 @@ mod native {
// A real table has at most one merge per cell; more ranges than that come from a
// damaged file and would only make this rows × cols × ranges.
let max_ranges = rows.saturating_mul(cols).min(1 << 16);
for r in t.merged_ranges.iter().take(max_ranges).cloned().collect::<Vec<_>>() {
for r in t.merged_ranges.iter().take(max_ranges).copied().collect::<Vec<_>>() {
// Clamp to the table: the ranges come from the file.
let (bottom, right) = (r.bottom_row.min(rows.saturating_sub(1)), r.right_col.min(cols.saturating_sub(1)));
if r.top_row > bottom || r.left_col > right || rows == 0 || cols == 0 || (r.top_row, r.left_col) == (bottom, right) {
@@ -715,8 +732,8 @@ mod native {
}
/// Leave out DGN line style components (`LS*COMPONENT`) that no line style definition uses
/// (#1482). A drawing that once came from MicroStation can carry hundreds of thousands of
/// them, orphaned copies piled up by earlier DGN imports and copy-pastes (AutoCAD's PURGE
/// (#1482). A drawing that once came from `MicroStation` can carry hundreds of thousands of
/// them, orphaned copies piled up by earlier DGN imports and copy-pastes (`AutoCAD`'s PURGE
/// removes them as orphaned data): in a real 83 MB site plan they were 888,483 of 889,053
/// components and made its DXF rendition 1.2 GB, over [`Limits::DEFAULT`], so the file
/// didn't open at all. No definition that was read refers to them (a definition the reader
@@ -846,7 +863,7 @@ mod native {
for (name, code, value) in unwritten_header_vars(h) {
let written = section.windows(name.len() + 2).any(|w| w.starts_with(name.as_bytes()) && w.ends_with(b"\r\n"));
if !written && value.parse::<f64>().is_ok_and(f64::is_finite) {
add.push_str(&format!(" 9\r\n{name}\r\n{code:>3}\r\n{value}\r\n"));
let _ = write!(add, " 9\r\n{name}\r\n{code:>3}\r\n{value}\r\n");
}
}
dxf.splice(end..end, add.into_bytes());
@@ -878,14 +895,22 @@ mod native {
/// Oldest DWG version written; older DXF input is written as this version.
const MIN_DWG_VERSION: acadrust::DxfVersion = acadrust::DxfVersion::AC1018;
/// Convert DXF bytes into a DWG file of the DXF's version, and at least AutoCAD 2004
/// Convert DXF bytes into a DWG file of the DXF's version, and at least `AutoCAD` 2004
/// (AC1018).
///
/// # Errors
///
/// Returns an error when the DXF cannot be decoded or the DWG cannot be written, including oversized input.
pub fn dxf_to_dwg(dxf: &[u8]) -> Result<Vec<u8>, String> {
convert(dxf, None, None).map(|(dwg, _)| dwg)
}
/// Convert DXF bytes into a DWG file of `version`, a code from [`super::VERSIONS`] ("AC1032"),
/// whatever version the DXF declares.
///
/// # Errors
///
/// Returns an error for an unsupported version, invalid DXF, oversized input, or a DWG write failure.
pub fn dxf_to_dwg_as(dxf: &[u8], version: &str) -> Result<Vec<u8>, String> {
dxf_to_dwg_noted(dxf, version).map(|(dwg, _)| dwg)
}
@@ -1011,7 +1036,7 @@ mod native {
/// The current dimension style (`$DIMSTYLE`) by its name: the DXF gives the name, and the
/// handle read with it needn't be the style's in the document, in which case the DWG writer
/// fell back to Standard and AutoCAD opened the drawing with Standard current (#1051).
/// fell back to Standard and `AutoCAD` opened the drawing with Standard current (#1051).
fn current_dimstyle(doc: &mut acadrust::CadDocument) {
let name = doc.header.current_dimstyle_name.clone();
if let Some(h) = doc.dim_styles.iter().find(|ds| ds.name.eq_ignore_ascii_case(&name)).map(|ds| ds.handle) {
@@ -1021,7 +1046,7 @@ mod native {
/// The current text style (`$TEXTSTYLE`) by its name, the same way as [`current_dimstyle`]:
/// the handle read with the DXF needn't be the style's in the document, in which case the DWG
/// writer fell back to Standard and AutoCAD opened the drawing with Standard current (#1650).
/// writer fell back to Standard and `AutoCAD` opened the drawing with Standard current (#1650).
fn current_text_style(doc: &mut acadrust::CadDocument) {
let name = doc.header.current_text_style_name.clone();
if let Some(h) = doc.text_styles.iter().find(|ts| ts.name.eq_ignore_ascii_case(&name)).map(|ts| ts.handle) {
@@ -1211,7 +1236,7 @@ mod native {
};
let (classes, source) = guarded(AssertUnwindSafe(|| (dxf_class_names(&data), super::proxy_transport::source_classes(&data))))
.map_err(|_| "the DXF proxy class conversion failed".to_string())?;
let mut doc = std::panic::catch_unwind(move || acadrust::DxfReader::from_reader(Cursor::new(data)).and_then(|r| r.read()))
let mut doc = std::panic::catch_unwind(move || acadrust::DxfReader::from_reader(Cursor::new(data)).and_then(acadrust::DxfReader::read))
.map_err(|_| "the DXF→DWG conversion failed".to_string())?
.map_err(|e| format!("DXF: {e}"))?;
match version {
@@ -1250,14 +1275,14 @@ mod native {
current_layer(&mut doc);
unwritten
}))
.map_err(|_| "the DXF to DWG conversion failed on this file".to_string())?;
.map_err(|()| "the DXF to DWG conversion failed on this file".to_string())?;
let dwg = std::panic::catch_unwind(AssertUnwindSafe(|| acadrust::DwgWriter::write_to_vec(&doc)))
.map_err(|_| "the DWG writer failed on this drawing".to_string())?
.map_err(|e| format!("DWG write: {e}"))?;
Ok((dwg, unwritten))
}
/// AutoCAD's entry name for the drawing variables dictionary (the DXF Reference calls it the
/// `AutoCAD`'s entry name for the drawing variables dictionary (the DXF Reference calls it the
/// ACDBVARIABLEDICTIONARY; dictionary keys are case-insensitive).
const VARIABLE_DICTIONARY: &str = "AcDbVariableDictionary";
@@ -1273,11 +1298,11 @@ mod native {
if valid.contains(&value) { value.to_string() } else { default.to_string() }
}
/// Add the drawing variables dictionary AutoCAD always writes into the named object
/// Add the drawing variables dictionary `AutoCAD` always writes into the named object
/// dictionary, with the variables it keeps there, when the drawing has none (#1813).
/// Vectric Aspire 10.5 reads a 2004 (AC1018) DWG without it as empty ("No data was imported
/// from the DXF / DWG file"), though it reads the same drawing as DXF — which has no such
/// dictionary either, as CADCraft's and ezdxf's writers don't make one. AutoCAD's AC1032 DWGs
/// dictionary either, as CADCraft's and ezdxf's writers don't make one. `AutoCAD`'s AC1032 DWGs
/// read there without it, so newer output is left as it was, and a dictionary the drawing
/// does have keeps its own entries and values.
fn add_variable_dictionary(doc: &mut acadrust::CadDocument) {
@@ -1326,7 +1351,7 @@ mod native {
/// Entities of a layout other than the one in `*Paper_Space` are written owned by their block
/// (entity mode 0, with its handle). acadrust writes every paper-space entity with mode 1,
/// "paper space", which AutoCAD reads as the `*Paper_Space` block's: everything drawn on a
/// "paper space", which `AutoCAD` reads as the `*Paper_Space` block's: everything drawn on a
/// second layout landed on the first one, and the second stayed empty (#1057).
fn other_layout_owners(doc: &mut acadrust::CadDocument) {
let others: std::collections::HashSet<acadrust::Handle> = doc
@@ -1549,11 +1574,11 @@ thread_local! {
/// Panics when a test asked for `stage` to fail (see [`PANIC_IN`]); does nothing otherwise.
#[cfg(not(no_dwg_bridge))]
#[allow(clippy::panic)]
fn fail_in_test(_stage: &str) {
fn fail_in_test(stage: &str) {
#[cfg(not(test))]
let _ = stage;
#[cfg(test)]
if PANIC_IN.with(|p| p.get()) == Some(_stage) {
panic!("test-forced panic in {_stage}");
}
assert!(PANIC_IN.with(std::cell::Cell::get) != Some(stage), "test-forced panic in {stage}");
}
/// The error for a DWG version this writer can't create.
@@ -1633,6 +1658,8 @@ pub fn dxf_to_dwg_kept_noted(_dxf: &[u8], _version: &str, _kept: &str) -> Result
#[cfg(test)]
mod tests {
use std::fmt::Write as _;
use super::*;
/// The DXF of an empty drawing, enough for the bridge to make a small DWG.
@@ -1726,9 +1753,9 @@ mod tests {
let mut s = String::from(" 0\nSECTION\n 2\nHEADER\n 9\n$ACADVER\n 1\nAC1032\n 0\nENDSEC\n 0\nSECTION\n 2\nENTITIES\n");
for (text, flags, sub, pts) in dims {
s += " 0\nDIMENSION\n 8\n0\n100\nAcDbEntity\n100\nAcDbDimension\n 10\n0\n 20\n0\n 30\n0\n";
s += &format!(" 11\n50\n 21\n-20\n 31\n0\n 70\n{flags}\n 1\n{text}\n 3\nStandard\n100\n{sub}\n");
for (code, [x, y]) in pts.iter() {
s += &format!("{code:>3}\n{x}\n{:>3}\n{y}\n{:>3}\n0\n", code + 10, code + 20);
let _ = write!(s, " 11\n50\n 21\n-20\n 31\n0\n 70\n{flags}\n 1\n{text}\n 3\nStandard\n100\n{sub}\n");
for (code, [x, y]) in *pts {
let _ = write!(s, "{code:>3}\n{x}\n{:>3}\n{y}\n{:>3}\n0\n", code + 10, code + 20);
}
}
s + " 0\nENDSEC\n 0\nEOF\n"
@@ -1797,13 +1824,17 @@ mod tests {
.collect()
}
/// Issue #1482: a DWG that once came from MicroStation can carry hundreds of thousands of DGN
/// Issue #1482: a DWG that once came from `MicroStation` can carry hundreds of thousands of DGN
/// line style components no definition uses (a real 83 MB site plan: 888,483 of 889,053, a
/// 1.2 GB DXF rendition over the limit, so it didn't open). They're left out with a note, and
/// their dictionary entries with them; the definition and every component it reaches —
/// through compound and point components, around a cycle — are kept.
#[cfg(not(no_dwg_bridge))]
#[test]
#[expect(
clippy::too_many_lines,
reason = "This integration test builds and verifies one complete DGN component graph; splitting the fixture would obscure reachability."
)]
fn orphaned_dgn_line_style_components_are_left_out() {
use acadrust::objects::*;
let mut doc = acadrust::CadDocument::new();
+774
View File
@@ -0,0 +1,774 @@
//! Incremental ASCII DXF file writer used by VectorCraft.
//!
//! This is the file skeleton around a pre-written `ENTITIES` section: group codes, handles, and
//! the HEADER / TABLES / BLOCKS / OBJECTS sections CAD apps expect. It is a different API from
//! [`crate::model::write`], which serializes a parsed [`crate::model`] drawing as tags.
//!
//! Moved from `vectorcraft-cad` (`crates/cad/src/writer.rs`). The bytes a [`Drawing`] writes must
//! stay the same: VectorCraft's export tests treat this as the format oracle.
//!
//! DXF R13 and later give every object a handle and subclass markers; R2000 and later add layouts
//! and plot styles.
use std::fmt::Write as _;
pub use crate::model::write::Format;
/// An object handle (written in hex).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Handle(pub u32);
/// The handles of the fixed objects every drawing has. Entities and table entries count up from
/// [`FIRST_FREE`].
pub mod fixed {
use super::Handle;
pub const LAYER_TABLE: Handle = Handle(0x1);
pub const LTYPE_TABLE: Handle = Handle(0x2);
pub const APPID_TABLE: Handle = Handle(0x3);
pub const DIMSTYLE_TABLE: Handle = Handle(0x4);
pub const STYLE_TABLE: Handle = Handle(0x5);
pub const UCS_TABLE: Handle = Handle(0x6);
pub const VIEW_TABLE: Handle = Handle(0x7);
pub const VPORT_TABLE: Handle = Handle(0x8);
pub const BLOCK_RECORD_TABLE: Handle = Handle(0x9);
pub const ROOT: Handle = Handle(0xA);
pub const GROUPS: Handle = Handle(0xB);
pub const LAYOUTS: Handle = Handle(0xC);
pub const MODEL_RECORD: Handle = Handle(0xD);
pub const PAPER_RECORD: Handle = Handle(0xE);
pub const MODEL_BLOCK: Handle = Handle(0xF);
pub const MODEL_END: Handle = Handle(0x10);
pub const PAPER_BLOCK: Handle = Handle(0x11);
pub const PAPER_END: Handle = Handle(0x12);
pub const MODEL_LAYOUT: Handle = Handle(0x13);
pub const PAPER_LAYOUT: Handle = Handle(0x14);
pub const ACTIVE_VPORT: Handle = Handle(0x15);
pub const ACAD_APPID: Handle = Handle(0x16);
pub const STANDARD_DIMSTYLE: Handle = Handle(0x17);
pub const IMAGE_DICT: Handle = Handle(0x18);
pub const IMAGE_VARS: Handle = Handle(0x19);
pub const PLOT_STYLES: Handle = Handle(0x1A);
pub const PLOT_NORMAL: Handle = Handle(0x1B);
pub const FIRST_FREE: u32 = 0x30;
}
/// A number as DXF writes it: up to 6 decimals, no trailing zeros, 0 for anything not finite.
pub fn num(v: f64) -> String {
if !v.is_finite() {
return "0".into();
}
let s = format!("{v:.6}");
let s = s.trim_end_matches('0').trim_end_matches('.');
if s == "-0" || s.is_empty() { "0".into() } else { s.into() }
}
/// Text as a DXF string value: one line, `^` escaped, and before DXF 2007 (which reads UTF-8)
/// every character outside ASCII as `\U+XXXX`.
pub fn text(s: &str, utf8: bool) -> String {
let mut out = String::with_capacity(s.len());
for c in s.chars() {
match c {
'\r' | '\n' | '\t' => out.push(' '),
c if c.is_control() => {}
'^' => out.push_str("^ "),
c if !utf8 && !c.is_ascii() => match u16::try_from(u32::from(c)) {
Ok(u) => _ = write!(out, "\\U+{u:04X}"),
Err(_) => out.push('?'),
},
c => out.push(c),
}
}
out
}
/// Group-code/value pairs in the order they are written.
pub struct Codes {
pub v: Format,
out: String,
}
impl Codes {
pub fn new(v: Format) -> Self {
Self { v, out: String::new() }
}
pub fn into_string(self) -> String {
self.out
}
pub fn append(&mut self, other: &str) {
self.out.push_str(other);
}
/// A value written as it is (names and keywords the writer itself chose).
pub fn raw(&mut self, code: u16, value: &str) {
_ = writeln!(self.out, "{code:>3}\n{value}");
}
/// Text from the document, encoded for the version (see [`text`]).
pub fn str(&mut self, code: u16, value: &str) {
let t = text(value, self.v.utf8());
self.raw(code, &t);
}
pub fn int(&mut self, code: u16, value: i64) {
_ = writeln!(self.out, "{code:>3}\n{value}");
}
pub fn num(&mut self, code: u16, value: f64) {
_ = writeln!(self.out, "{code:>3}\n{}", num(value));
}
pub fn handle(&mut self, code: u16, h: Handle) {
_ = writeln!(self.out, "{code:>3}\n{:X}", h.0);
}
/// A 2D point at `code` (x), `code + 10` (y).
pub fn xy(&mut self, code: u16, x: f64, y: f64) {
self.num(code, x);
self.num(code + 10, y);
}
/// A 3D point at `code`, `code + 10`, `code + 20` (z = 0).
pub fn xyz(&mut self, code: u16, x: f64, y: f64) {
self.xy(code, x, y);
self.num(code + 20, 0.0);
}
/// The extrusion direction of planar entities: the z axis.
pub fn normal(&mut self) {
self.num(210, 0.0);
self.num(220, 0.0);
self.num(230, 1.0);
}
/// The start of an object: its type, and from R13 its handle, owner and first subclass.
fn object(&mut self, kind: &str, h: Handle, owner: Handle, subclass: &str) {
self.raw(0, kind);
if self.v.handles() {
self.handle(if kind == "DIMSTYLE" { 105 } else { 5 }, h);
self.handle(330, owner);
self.raw(100, subclass);
}
}
/// A table entry: the shared record subclass, then the table's own (from R13).
fn record(&mut self, kind: &str, h: Handle, table: Handle, subclass: &str) {
self.object(kind, h, table, "AcDbSymbolTableRecord");
if self.v.handles() {
self.raw(100, subclass);
}
}
fn section(&mut self, name: &str) {
self.raw(0, "SECTION");
self.raw(2, name);
}
fn end_section(&mut self) {
self.raw(0, "ENDSEC");
}
fn table(&mut self, name: &str, h: Handle, count: usize) {
self.raw(0, "TABLE");
self.raw(2, name);
if self.v.handles() {
self.handle(5, h);
self.raw(330, "0");
self.raw(100, "AcDbSymbolTable");
}
self.int(70, count as i64);
if name == "DIMSTYLE" && self.v.r2000() {
self.raw(100, "AcDbDimStyleTable");
}
}
fn end_table(&mut self) {
self.raw(0, "ENDTAB");
}
}
/// How an entity is drawn: its colour index, true colour, lineweight, linetype and transparency.
#[derive(Clone, Debug, Default)]
pub struct EntityStyle {
pub aci: u8,
/// `0xRRGGBB` (DXF 2004 and later).
pub rgb: Option<u32>,
/// Hundredths of a millimetre (DXF 2000 and later).
pub lineweight: Option<i32>,
pub linetype: Option<String>,
/// Opacity 0–255 (DXF 2004 and later; opaque is left out).
pub alpha: Option<u8>,
}
impl Codes {
/// The start of an entity of `kind` owned by `owner` (model space, or a polyline for its
/// vertices) on `layer` with its style, ending with `subclass` (none when empty).
pub fn entity(&mut self, kind: &str, h: Handle, owner: Handle, layer: &str, style: &EntityStyle, subclass: &str) {
self.object(kind, h, owner, "AcDbEntity");
self.str(8, layer);
if let Some(lt) = &style.linetype {
self.str(6, lt);
}
self.int(62, i64::from(style.aci));
if self.v.r2000()
&& let Some(lw) = style.lineweight
{
self.int(370, i64::from(lw));
}
if self.v.true_color() {
if let Some(rgb) = style.rgb {
self.int(420, i64::from(rgb));
}
if let Some(a) = style.alpha {
self.int(440, 0x0200_0000 | i64::from(a));
}
}
if self.v.handles() && !subclass.is_empty() {
self.raw(100, subclass);
}
}
}
/// A DXF layer.
#[derive(Clone, Debug)]
pub struct Layer {
pub name: String,
pub aci: u8,
/// Switched off (a hidden layer).
pub off: bool,
pub locked: bool,
/// Plotted (printable).
pub plot: bool,
}
/// A dash pattern: dash, gap, dash… lengths in drawing units.
#[derive(Clone, Debug)]
pub struct LineType {
pub name: String,
pub pattern: Vec<f64>,
}
/// A placed image file and the image entities that show it.
#[derive(Clone, Debug)]
pub struct ImageDef {
pub name: String,
pub size: (u32, u32),
pub handle: Handle,
/// `(reactor, image entity)` per image entity.
pub reactors: Vec<(Handle, Handle)>,
}
/// Everything around the entities, collected while they were written.
pub struct Drawing {
pub version: Format,
pub layers: Vec<Layer>,
pub linetypes: Vec<LineType>,
/// Text styles: (style name, font family).
pub styles: Vec<(String, String)>,
pub images: Vec<ImageDef>,
/// The entities' group codes.
pub entities: String,
/// `[x0, y0, x1, y1]` of everything written (drawing units).
pub extents: [f64; 4],
/// The export region (drawing units).
pub limits: [f64; 4],
/// `$INSUNITS`.
pub insunits: u8,
pub metric: bool,
/// The next free handle.
pub next: u32,
}
/// The text style every drawing has.
pub const STANDARD_STYLE: &str = "Standard";
impl Drawing {
/// The whole file.
pub fn write(self) -> String {
let v = self.version;
let mut c = Codes::new(v);
// Table entries get the handles after the entities'.
let mut next = self.next;
let mut take = |n: usize| {
let start = next;
next = next.saturating_add(u32::try_from(n).unwrap_or(u32::MAX));
start
};
let ltype_base = take(3 + self.linetypes.len());
let layer_base = take(1 + self.layers.len());
let style_base = take(1 + self.styles.len());
self.header(&mut c, next);
if v.handles() {
self.classes(&mut c);
}
c.section("TABLES");
self.vport(&mut c);
self.ltypes(&mut c, ltype_base);
self.layer_table(&mut c, layer_base);
self.style_table(&mut c, style_base);
if v.handles() {
for (name, h) in [("VIEW", fixed::VIEW_TABLE), ("UCS", fixed::UCS_TABLE)] {
c.table(name, h, 0);
c.end_table();
}
c.table("APPID", fixed::APPID_TABLE, 1);
c.record("APPID", fixed::ACAD_APPID, fixed::APPID_TABLE, "AcDbRegAppTableRecord");
c.raw(2, "ACAD");
c.int(70, 0);
c.end_table();
c.table("DIMSTYLE", fixed::DIMSTYLE_TABLE, 1);
c.record("DIMSTYLE", fixed::STANDARD_DIMSTYLE, fixed::DIMSTYLE_TABLE, "AcDbDimStyleTableRecord");
c.raw(2, "Standard");
c.int(70, 0);
c.end_table();
c.table("BLOCK_RECORD", fixed::BLOCK_RECORD_TABLE, 2);
for (name, h, layout) in
[("*Model_Space", fixed::MODEL_RECORD, fixed::MODEL_LAYOUT), ("*Paper_Space", fixed::PAPER_RECORD, fixed::PAPER_LAYOUT)]
{
c.record("BLOCK_RECORD", h, fixed::BLOCK_RECORD_TABLE, "AcDbBlockTableRecord");
c.raw(2, name);
if v.r2000() {
c.handle(340, layout);
c.int(70, 0);
c.int(280, 1);
c.int(281, 0);
}
}
c.end_table();
}
c.end_section();
if v.handles() {
c.section("BLOCKS");
for (name, record, begin, end) in [
("*Model_Space", fixed::MODEL_RECORD, fixed::MODEL_BLOCK, fixed::MODEL_END),
("*Paper_Space", fixed::PAPER_RECORD, fixed::PAPER_BLOCK, fixed::PAPER_END),
] {
c.object("BLOCK", begin, record, "AcDbEntity");
c.raw(8, "0");
c.raw(100, "AcDbBlockBegin");
c.raw(2, name);
c.int(70, 0);
c.xyz(10, 0.0, 0.0);
c.raw(3, name);
c.raw(1, "");
c.object("ENDBLK", end, record, "AcDbEntity");
c.raw(8, "0");
c.raw(100, "AcDbBlockEnd");
}
c.end_section();
}
c.section("ENTITIES");
c.append(&self.entities);
c.end_section();
if v.handles() {
self.objects(&mut c);
}
c.raw(0, "EOF");
c.into_string()
}
fn header(&self, c: &mut Codes, handseed: u32) {
let v = self.version;
let var = |c: &mut Codes, name: &str| c.raw(9, name);
c.section("HEADER");
var(c, "$ACADVER");
c.raw(1, v.acadver());
var(c, "$DWGCODEPAGE");
c.raw(3, "ANSI_1252");
var(c, "$INSBASE");
c.xyz(10, 0.0, 0.0);
let [x0, y0, x1, y1] = self.extents;
var(c, "$EXTMIN");
c.xyz(10, x0, y0);
var(c, "$EXTMAX");
c.xyz(10, x1, y1);
let [lx0, ly0, lx1, ly1] = self.limits;
var(c, "$LIMMIN");
c.xy(10, lx0, ly0);
var(c, "$LIMMAX");
c.xy(10, lx1, ly1);
if v.r2000() {
var(c, "$LWDISPLAY");
c.int(290, 1);
var(c, "$INSUNITS");
c.int(70, i64::from(self.insunits));
var(c, "$MEASUREMENT");
c.int(70, i64::from(self.metric));
}
if v.handles() {
var(c, "$HANDSEED");
c.handle(5, Handle(handseed));
}
c.end_section();
}
fn classes(&self, c: &mut Codes) {
let mut classes: Vec<(&str, &str, &str, i64, bool)> = vec![];
if self.version.r2000() {
classes.extend([
("ACDBDICTIONARYWDFLT", "AcDbDictionaryWithDefault", "ObjectDBX Classes", 0, false),
("ACDBPLACEHOLDER", "AcDbPlaceHolder", "ObjectDBX Classes", 0, false),
("LAYOUT", "AcDbLayout", "ObjectDBX Classes", 0, false),
]);
}
if !self.images.is_empty() {
classes.extend([
("RASTERVARIABLES", "AcDbRasterVariables", "ISM", 0, false),
("IMAGE", "AcDbRasterImage", "ISM", 2175, true),
("IMAGEDEF", "AcDbRasterImageDef", "ISM", 0, false),
("IMAGEDEF_REACTOR", "AcDbRasterImageDefReactor", "ISM", 1, false),
]);
}
c.section("CLASSES");
for (name, cpp, app, flags, entity) in classes {
c.raw(0, "CLASS");
c.raw(1, name);
c.raw(2, cpp);
c.raw(3, app);
c.int(90, flags);
if self.version.true_color() {
c.int(91, 0);
}
c.int(280, 0);
c.int(281, i64::from(entity));
}
c.end_section();
}
/// The active viewport, zoomed to the drawing's extents.
fn vport(&self, c: &mut Codes) {
let [x0, y0, x1, y1] = self.extents;
c.table("VPORT", fixed::VPORT_TABLE, 1);
c.record("VPORT", fixed::ACTIVE_VPORT, fixed::VPORT_TABLE, "AcDbViewportTableRecord");
c.raw(2, if self.version.handles() { "*Active" } else { "*ACTIVE" });
c.int(70, 0);
c.xy(10, 0.0, 0.0);
c.xy(11, 1.0, 1.0);
c.xy(12, (x0 + x1) / 2.0, (y0 + y1) / 2.0);
c.xy(13, 0.0, 0.0);
c.xy(14, 1.0, 1.0);
c.xy(15, 10.0, 10.0);
// The view direction looks down the z axis: (0, 0, 1), each code once.
c.xy(16, 0.0, 0.0);
c.num(36, 1.0);
c.xyz(17, 0.0, 0.0);
let (w, h) = ((x1 - x0).abs(), (y1 - y0).abs());
// The view's height, with a margin; its width follows from the aspect ratio.
c.num(40, (h.max(w / 1.5) * 1.1).max(1.0));
c.num(41, 1.5);
c.num(42, 50.0);
c.num(43, 0.0);
c.num(44, 0.0);
c.num(50, 0.0);
c.num(51, 0.0);
for (code, value) in [(71, 0), (72, 1000), (73, 1), (74, 3), (75, 0), (76, 0), (77, 0), (78, 0)] {
c.int(code, value);
}
if self.version.r2000() {
c.int(281, 0);
c.int(65, 0);
c.num(146, 0.0);
}
c.end_table();
}
fn ltypes(&self, c: &mut Codes, base: u32) {
c.table("LTYPE", fixed::LTYPE_TABLE, 3 + self.linetypes.len());
let solid = [("ByBlock", ""), ("ByLayer", ""), ("Continuous", "Solid line")];
let rows = solid.iter().map(|(n, d)| (*n, *d, &[][..])).chain(self.linetypes.iter().map(|l| (l.name.as_str(), "", l.pattern.as_slice())));
for (i, (name, desc, pattern)) in rows.enumerate() {
c.record("LTYPE", Handle(base.saturating_add(i as u32)), fixed::LTYPE_TABLE, "AcDbLinetypeTableRecord");
c.str(2, name);
c.int(70, 0);
c.str(3, if pattern.is_empty() { desc } else { "Dashed" });
c.int(72, 65);
c.int(73, pattern.len() as i64);
c.num(40, pattern.iter().map(|v| v.abs()).sum());
for v in pattern {
c.num(49, *v);
if self.version.handles() {
c.int(74, 0);
}
}
}
c.end_table();
}
fn layer_table(&self, c: &mut Codes, base: u32) {
let zero = Layer { name: "0".into(), aci: 7, off: false, locked: false, plot: true };
c.table("LAYER", fixed::LAYER_TABLE, 1 + self.layers.len());
for (i, l) in std::iter::once(&zero).chain(&self.layers).enumerate() {
c.record("LAYER", Handle(base.saturating_add(i as u32)), fixed::LAYER_TABLE, "AcDbLayerTableRecord");
c.str(2, &l.name);
c.int(70, if l.locked { 4 } else { 0 });
// A negative colour switches the layer off.
let aci = i64::from(l.aci.max(1));
c.int(62, if l.off { -aci } else { aci });
c.raw(6, "Continuous");
if self.version.r2000() {
c.int(290, i64::from(l.plot));
c.int(370, -3);
c.handle(390, fixed::PLOT_NORMAL);
}
}
c.end_table();
}
fn style_table(&self, c: &mut Codes, base: u32) {
c.table("STYLE", fixed::STYLE_TABLE, 1 + self.styles.len());
let standard = (STANDARD_STYLE.to_string(), String::new());
for (i, (name, family)) in std::iter::once(&standard).chain(&self.styles).enumerate() {
c.record("STYLE", Handle(base.saturating_add(i as u32)), fixed::STYLE_TABLE, "AcDbTextStyleTableRecord");
c.str(2, name);
c.int(70, 0);
c.num(40, 0.0);
c.num(41, 1.0);
c.num(50, 0.0);
c.int(71, 0);
c.num(42, 2.5);
// The font file; from 2000 the family name too, which is how CAD apps find a TrueType font.
if family.is_empty() {
c.raw(3, "txt");
} else {
c.str(3, &format!("{family}.ttf"));
}
c.raw(4, "");
if self.version.r2000() && !family.is_empty() {
c.raw(1001, "ACAD");
c.str(1000, family);
c.int(1071, 0);
}
}
c.end_table();
}
fn objects(&self, c: &mut Codes) {
let v = self.version;
let images = !self.images.is_empty();
c.section("OBJECTS");
let dict = |c: &mut Codes, h: Handle, owner: Handle, entries: &[(&str, Handle)]| {
c.object("DICTIONARY", h, owner, "AcDbDictionary");
c.int(281, 1);
for (name, e) in entries {
c.str(3, name);
c.handle(350, *e);
}
};
let mut root = vec![("ACAD_GROUP", fixed::GROUPS)];
if images {
root.extend([("ACAD_IMAGE_DICT", fixed::IMAGE_DICT), ("ACAD_IMAGE_VARS", fixed::IMAGE_VARS)]);
}
if v.r2000() {
root.extend([("ACAD_LAYOUT", fixed::LAYOUTS), ("ACAD_PLOTSTYLENAME", fixed::PLOT_STYLES)]);
}
dict(c, fixed::ROOT, Handle(0), &root);
dict(c, fixed::GROUPS, fixed::ROOT, &[]);
if v.r2000() {
dict(c, fixed::LAYOUTS, fixed::ROOT, &[("Layout1", fixed::PAPER_LAYOUT), ("Model", fixed::MODEL_LAYOUT)]);
c.object("ACDBDICTIONARYWDFLT", fixed::PLOT_STYLES, fixed::ROOT, "AcDbDictionary");
c.int(281, 1);
c.raw(3, "Normal");
c.handle(350, fixed::PLOT_NORMAL);
c.raw(100, "AcDbDictionaryWithDefault");
c.handle(340, fixed::PLOT_NORMAL);
// A placeholder has no data and no subclass marker of its own.
c.raw(0, "ACDBPLACEHOLDER");
c.handle(5, fixed::PLOT_NORMAL);
c.handle(330, fixed::PLOT_STYLES);
self.layout(c, fixed::MODEL_LAYOUT, "Model", 0, fixed::MODEL_RECORD);
self.layout(c, fixed::PAPER_LAYOUT, "Layout1", 1, fixed::PAPER_RECORD);
}
if images {
c.object("RASTERVARIABLES", fixed::IMAGE_VARS, fixed::ROOT, "AcDbRasterVariables");
c.int(90, 0);
c.int(70, 0);
c.int(71, 1);
c.int(72, 0);
let keys: Vec<String> = self.images.iter().map(|i| format!("IMAGE_{:X}", i.handle.0)).collect();
let entries: Vec<(&str, Handle)> = keys.iter().zip(&self.images).map(|(key, image)| (key.as_str(), image.handle)).collect();
dict(c, fixed::IMAGE_DICT, fixed::ROOT, &entries);
for img in &self.images {
c.raw(0, "IMAGEDEF");
c.handle(5, img.handle);
c.raw(102, "{ACAD_REACTORS");
c.handle(330, fixed::IMAGE_DICT);
for (reactor, _) in &img.reactors {
c.handle(330, *reactor);
}
c.raw(102, "}");
c.handle(330, fixed::IMAGE_DICT);
c.raw(100, "AcDbRasterImageDef");
c.int(90, 0);
c.str(1, &img.name);
c.xy(10, f64::from(img.size.0), f64::from(img.size.1));
c.xy(11, 1.0, 1.0);
c.int(280, 1);
c.int(281, 0);
for (reactor, image) in &img.reactors {
c.object("IMAGEDEF_REACTOR", *reactor, *image, "AcDbRasterImageDefReactor");
c.int(90, 2);
c.handle(330, *image);
}
}
}
c.end_section();
}
/// A layout (DXF 2000 and later): its plot settings, then the layout itself.
fn layout(&self, c: &mut Codes, h: Handle, name: &str, tab: i64, record: Handle) {
let [x0, y0, x1, y1] = self.extents;
c.object("LAYOUT", h, fixed::LAYOUTS, "AcDbPlotSettings");
c.raw(1, "");
c.raw(2, "none_device");
c.raw(4, "");
c.raw(6, "");
for code in 40..=49 {
c.num(code, 0.0);
}
c.num(140, 0.0);
c.num(141, 0.0);
c.num(142, 1.0);
c.num(143, 1.0);
// Plot flags; 1024 marks the model space layout.
c.int(70, if record == fixed::MODEL_RECORD { 688 | 1024 } else { 688 });
c.int(72, 1);
c.int(73, 0);
c.int(74, 5);
c.raw(7, "");
c.int(75, 16);
if self.version.true_color() {
// Shade plot mode (as displayed), resolution level (normal) and custom DPI.
c.int(76, 0);
c.int(77, 2);
c.int(78, 300);
}
c.num(147, 1.0);
// The paper image origin is 148 (x) and 149 (y), not a point at 148 and 158.
c.num(148, 0.0);
c.num(149, 0.0);
c.raw(100, "AcDbLayout");
c.raw(1, name);
c.int(70, 1);
c.int(71, tab);
let [lx0, ly0, lx1, ly1] = self.limits;
c.xy(10, lx0, ly0);
c.xy(11, lx1, ly1);
c.xyz(12, 0.0, 0.0);
c.xyz(14, x0, y0);
c.xyz(15, x1, y1);
c.num(146, 0.0);
c.xyz(13, 0.0, 0.0);
c.xyz(16, 1.0, 0.0);
c.xyz(17, 0.0, 1.0);
c.int(76, 1);
c.handle(330, record);
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn numbers_and_text_are_written_plainly() {
assert_eq!(num(1.5), "1.5");
assert_eq!(num(-0.0000001), "0");
assert_eq!(num(2.0), "2");
assert_eq!(num(f64::NAN), "0");
assert_eq!(text("a^b\nc", true), "a^ b c");
assert_eq!(text("Größe 😀", false), "Gr\\U+00F6\\U+00DFe ?");
assert_eq!(text("Größe", true), "Größe");
}
/// A line from (0, 0) to (10, 20) on layer `Layer1`, in the style scene.rs writes entities.
fn line_entities(v: Format) -> String {
let mut e = Codes::new(v);
let style = EntityStyle { aci: 1, rgb: Some(0xFF0000), lineweight: Some(25), linetype: None, alpha: None };
e.entity("LINE", Handle(fixed::FIRST_FREE), fixed::MODEL_RECORD, "Layer1", &style, "AcDbLine");
e.xyz(10, 0.0, 0.0);
e.xyz(11, 10.0, 20.0);
e.into_string()
}
fn sample(v: Format, with_line: bool) -> Drawing {
Drawing {
version: v,
layers: vec![Layer { name: "Layer1".into(), aci: 1, off: false, locked: false, plot: true }],
linetypes: vec![],
styles: vec![],
images: vec![],
entities: if with_line { line_entities(v) } else { String::new() },
extents: [0.0, 0.0, 200.0, 100.0],
limits: [0.0, 0.0, 200.0, 100.0],
insunits: 4,
metric: true,
next: fixed::FIRST_FREE + if with_line { 1 } else { 0 },
}
}
fn assert_golden(name: &str, got: &str) {
let path = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/data").join(name);
if std::env::var_os("WRITE_DXF_GOLDENS").is_some() {
std::fs::create_dir_all(path.parent().expect("parent")).expect("mkdir");
std::fs::write(&path, got).expect("write golden");
return;
}
let expected = std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("read {}: {e}", path.display()));
assert_eq!(got, expected, "bytes changed versus {}", path.display());
}
use std::path::PathBuf;
#[test]
fn empty_and_line_drawings_match_goldens() {
for (name, v, line) in [
("drawing_empty_r12.dxf", Format::R12, false),
("drawing_empty_r2018.dxf", Format::R2018, false),
("drawing_line_r12.dxf", Format::R12, true),
("drawing_line_r2000.dxf", Format::R2000, true),
("drawing_line_r2018.dxf", Format::R2018, true),
] {
assert_golden(name, &sample(v, line).write());
}
}
#[test]
fn entity_preserves_byblock_colour() {
for v in Format::ALL {
let mut c = Codes::new(v);
c.entity("LINE", Handle(fixed::FIRST_FREE), fixed::MODEL_RECORD, "0", &EntityStyle::default(), "AcDbLine");
assert!(c.into_string().contains(" 62\n0\n"), "{v:?}");
}
}
#[test]
fn image_dictionary_keys_are_independent_of_filenames() {
let mut drawing = sample(Format::R2018, false);
for (index, name) in [r"C:\images\scan,1.png", "scan,1.png"].into_iter().enumerate() {
drawing.images.push(ImageDef { name: name.into(), size: (10, 20), handle: Handle(fixed::FIRST_FREE + index as u32), reactors: vec![] });
}
drawing.next = fixed::FIRST_FREE + 2;
let images = drawing.images.clone();
let output = drawing.write();
for image in &images {
assert!(output.contains(&format!(" 3\nIMAGE_{:X}\n350\n{:X}\n", image.handle.0, image.handle.0)));
assert!(output.contains(&format!(" 1\n{}\n", image.name)));
assert!(!output.contains(&format!(" 3\n{}\n", image.name)));
}
}
#[test]
fn every_format_writes_its_acadver_and_ends_at_eof() {
for v in Format::ALL {
let s = sample(v, true).write();
assert!(s.contains(&format!(" 1\n{}\n", v.acadver())), "{v:?}");
assert!(s.ends_with(" 0\nEOF\n"), "{v:?}");
if v.handles() {
assert!(s.contains(" 0\nSECTION\n 2\nCLASSES\n"), "{v:?}");
} else {
assert!(!s.contains("\nCLASSES\n"), "{v:?}");
}
}
}
}
+8 -3
View File
@@ -3,14 +3,18 @@
//! DXF is a sequence of (group code, value) pairs. This crate parses ASCII and binary DXF into a
//! flat list of [`Tag`]s, splits them into sections and entities, and writes tags back. [`model`]
//! reads the tags as a drawing (header variables, tables, blocks, entities, objects); mapping
//! that onto an application's own document is left to the caller. Written from Autodesk's
//! that onto an application's own document is left to the caller. [`drawing`] writes an ASCII
//! file around a pre-built `ENTITIES` section (VectorCraft's writer). Written from Autodesk's
//! published DXF Reference; depends on no other Craft crate. Moved from CADCraft's `cadcraft-dxf`.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
use std::io::Write as _;
pub mod drawing;
pub mod model;
pub mod mtext;
pub mod mtext_tokens;
pub mod paths;
mod version;
pub use version::Version;
@@ -195,8 +199,9 @@ pub use codepage::decode_code_page;
/// # Errors
///
/// Returns an error for empty input, an invalid group code, an incomplete group-code/value pair,
/// truncated binary data, or more than [`MAX_TAGS`] group codes. For ASCII input, invalid numeric
/// text becomes `0.0` for real values or `0` for integer values, and an EOF tag is not required.
/// truncated binary data, or more group codes than the limit returned by [`max_tags()`], which is
/// [`MAX_TAGS`] by default. For ASCII input, invalid numeric text becomes `0.0` for real values or
/// `0` for integer values, and an EOF tag is not required.
pub fn parse(bytes: &[u8]) -> Result<Vec<Tag>> {
parse_with_limit(bytes, max_tags())
}
+103
View File
@@ -0,0 +1,103 @@
//! MTEXT inline-escape handling independent of drawing and text layout.
//!
//! Unicode and MIF escapes are decoded to literal characters, with markup-significant
//! characters re-escaped so subsequent MTEXT parsers cannot treat them as commands.
/// Whether an inline command takes an argument terminated by `;`.
pub fn takes_arg(code: char) -> bool {
matches!(code, 'f' | 'F' | 'H' | 'W' | 'Q' | 'T' | 'A' | 'C' | 'c' | 'p')
}
/// Four hex digits at `chars[at..at + 4]`.
fn hex4(chars: &[char], at: usize) -> Option<u32> {
let digits = chars.get(at..at.checked_add(4)?)?;
digits.iter().try_fold(0u32, |acc, c| Some(acc * 16 + c.to_digit(16)?))
}
/// Push a decoded character so that the tokenizers read it as text, never as markup.
fn push_literal(out: &mut String, c: char) {
if matches!(c, '\\' | '{' | '}') {
out.push('\\');
}
out.push(c);
}
/// Decode `\U+hhhh` (one UTF-16 unit; a surrogate pair gives one character, a lone surrogate
/// U+FFFD) and `\M+nhhhh` (double-byte East Asian characters) to the characters they stand
/// for. Malformed escapes remain unchanged for the caller to interpret.
/// An escaped backslash (`\\U+0041`) is not an escape.
pub fn unescape_codes(s: &str) -> std::borrow::Cow<'_, str> {
if !s.contains("\\U+") && !s.contains("\\M+") {
return std::borrow::Cow::Borrowed(s);
}
let chars: Vec<char> = s.chars().collect();
let mut out = String::with_capacity(s.len());
let mut i = 0;
while let Some(&c) = chars.get(i) {
if c != '\\' {
out.push(c);
i += 1;
continue;
}
let (n, plus) = (chars.get(i + 1).copied(), chars.get(i + 2).copied());
if n == Some('U') && plus == Some('+') {
if let Some(unit) = hex4(&chars, i + 3) {
i += 7;
let low = |at: usize| {
(chars.get(at) == Some(&'\\') && chars.get(at + 1) == Some(&'U') && chars.get(at + 2) == Some(&'+'))
.then(|| hex4(&chars, at + 3))
.flatten()
.filter(|u| (0xDC00..0xE000).contains(u))
};
let ch = if (0xD800..0xDC00).contains(&unit) {
match low(i) {
Some(lo) => {
i += 7;
char::from_u32(0x10000 + ((unit - 0xD800) << 10) + (lo - 0xDC00))
}
None => None,
}
} else {
char::from_u32(unit)
};
push_literal(&mut out, ch.unwrap_or('\u{fffd}'));
continue;
}
} else if n == Some('M') && plus == Some('+') && chars.get(i + 3).is_some_and(char::is_ascii_digit) && hex4(&chars, i + 4).is_some() {
push_literal(&mut out, crate::mif_escape_at(&chars, i).unwrap_or('\u{fffd}'));
i += 8;
continue;
}
// Any other backslash pair stays as it is (and an escaped backslash stays one).
out.push('\\');
i += 1;
if let Some(&next) = chars.get(i) {
out.push(next);
i += 1;
}
}
std::borrow::Cow::Owned(out)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn unicode_and_mif_escapes_remain_literal_markup() {
assert_eq!(unescape_codes(r"a\U+0041\U+D83D\U+DE00"), "aA😀");
assert_eq!(unescape_codes(r"\M+5BCFE"), "件");
assert_eq!(unescape_codes(r"\U+005C\U+007B\U+007D"), r"\\\{\}");
assert_eq!(unescape_codes(r"\\U+0041"), r"\\U+0041");
assert_eq!(unescape_codes(r"\U+12"), r"\U+12");
assert_eq!(unescape_codes(r"\U+D800"), "�");
}
#[test]
fn parameterized_commands_are_classified_without_relaxing_others() {
for c in "fFHWQTACcp".chars() {
assert!(takes_arg(c));
}
for c in ['S', 'P', 'Z', '\\'] {
assert!(!takes_arg(c));
}
}
}
+132
View File
@@ -0,0 +1,132 @@
//! Streaming lexical tokens for MTEXT inline markup.
//!
//! Apply [`crate::mtext::unescape_codes`] first when Unicode/MIF escapes should become literal
//! characters. Tokens borrow their source and scanning allocates no memory. The consumer owns
//! formatting, line layout, paragraph policy and how unknown commands are displayed.
/// How a stacked-text argument finds its closing semicolon.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum StackMode {
/// The first semicolon ends the stack, as plain-text extraction historically did.
Plain,
/// A backslash quotes the next character, as the structured layout parser does.
Structured,
}
/// One lexical unit. Unknown commands retain their letter so the caller chooses compatibility.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Token<'a> {
Char(char),
OpenGroup,
CloseGroup,
Control(char),
Argument(char, &'a str),
Stack(&'a str),
Unknown(char),
}
/// A bounded-memory walk of UTF-8 MTEXT markup.
pub struct Tokens<'a> {
source: &'a str,
offset: usize,
stack_mode: StackMode,
}
impl<'a> Tokens<'a> {
pub fn new(source: &'a str, stack_mode: StackMode) -> Self {
Self { source, offset: 0, stack_mode }
}
fn next_char(&mut self) -> Option<char> {
let c = self.source.get(self.offset..)?.chars().next()?;
self.offset += c.len_utf8();
Some(c)
}
fn argument(&mut self, structured: bool) -> &'a str {
let start = self.offset;
let mut end = start;
while let Some(c) = self.next_char() {
if c == ';' {
return self.source.get(start..end).unwrap_or_default();
}
if structured && c == '\\' {
let _ = self.next_char();
}
end = self.offset;
}
self.source.get(start..end).unwrap_or_default()
}
}
impl<'a> Iterator for Tokens<'a> {
type Item = Token<'a>;
fn next(&mut self) -> Option<Self::Item> {
let c = self.next_char()?;
Some(match c {
'{' => Token::OpenGroup,
'}' => Token::CloseGroup,
'\\' => {
let code = self.next_char()?;
match code {
'S' => Token::Stack(self.argument(self.stack_mode == StackMode::Structured)),
c if crate::mtext::takes_arg(c) => Token::Argument(c, self.argument(false)),
c @ ('P' | 'N' | '~' | '\\' | '{' | '}' | 'L' | 'l' | 'O' | 'o' | 'K' | 'k') => Token::Control(c),
c => Token::Unknown(c),
}
}
c => Token::Char(c),
})
}
}
/// Split a structured stack into top, bottom and separator, unquoting escaped characters.
pub fn split_stack(raw: &str) -> (String, String, Option<char>) {
let (mut top, mut bottom, mut separator) = (String::new(), String::new(), None);
let mut chars = raw.chars();
while let Some(c) = chars.next() {
if c == '\\' {
if let Some(c) = chars.next() {
if separator.is_none() {
top.push(c);
} else {
bottom.push(c);
}
}
} else if separator.is_none() && matches!(c, '/' | '#' | '^') {
separator = Some(c);
} else if separator.is_none() {
top.push(c);
} else {
bottom.push(c);
}
}
(top, bottom, separator)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn tokens_borrow_text_and_preserve_unknown_commands() {
let got: Vec<_> = Tokens::new(r"A\Z\P{\H2x;x}\S1/2;", StackMode::Structured).collect();
assert_eq!(
got,
[
Token::Char('A'),
Token::Unknown('Z'),
Token::Control('P'),
Token::OpenGroup,
Token::Argument('H', "2x"),
Token::Char('x'),
Token::CloseGroup,
Token::Stack("1/2")
]
);
assert_eq!(split_stack("1/2"), ("1".into(), "2".into(), Some('/')));
}
#[test]
fn stacked_text_uses_the_requested_terminator_rules() {
let text = r"\Sa\;b/c;X";
assert_eq!(Tokens::new(text, StackMode::Plain).next(), Some(Token::Stack(r"a\")));
assert_eq!(Tokens::new(text, StackMode::Structured).next(), Some(Token::Stack(r"a\;b/c")));
assert_eq!(split_stack(r"a\;b/c"), ("a;b".into(), "c".into(), Some('/')));
}
#[test]
fn missing_terminator_and_trailing_backslash_are_bounded() {
assert_eq!(Tokens::new("\\H2x", StackMode::Structured).collect::<Vec<_>>(), [Token::Argument('H', "2x")]);
assert_eq!(Tokens::new("a\\", StackMode::Structured).collect::<Vec<_>>(), [Token::Char('a')]);
}
}
+250
View File
@@ -0,0 +1,250 @@
0
SECTION
2
HEADER
9
$ACADVER
1
AC1009
9
$DWGCODEPAGE
3
ANSI_1252
9
$INSBASE
10
0
20
0
30
0
9
$EXTMIN
10
0
20
0
30
0
9
$EXTMAX
10
200
20
100
30
0
9
$LIMMIN
10
0
20
0
9
$LIMMAX
10
200
20
100
0
ENDSEC
0
SECTION
2
TABLES
0
TABLE
2
VPORT
70
1
0
VPORT
2
*ACTIVE
70
0
10
0
20
0
11
1
21
1
12
100
22
50
13
0
23
0
14
1
24
1
15
10
25
10
16
0
26
0
36
1
17
0
27
0
37
0
40
146.666667
41
1.5
42
50
43
0
44
0
50
0
51
0
71
0
72
1000
73
1
74
3
75
0
76
0
77
0
78
0
0
ENDTAB
0
TABLE
2
LTYPE
70
3
0
LTYPE
2
ByBlock
70
0
3
72
65
73
0
40
0
0
LTYPE
2
ByLayer
70
0
3
72
65
73
0
40
0
0
LTYPE
2
Continuous
70
0
3
Solid line
72
65
73
0
40
0
0
ENDTAB
0
TABLE
2
LAYER
70
2
0
LAYER
2
0
70
0
62
7
6
Continuous
0
LAYER
2
Layer1
70
0
62
1
6
Continuous
0
ENDTAB
0
TABLE
2
STYLE
70
1
0
STYLE
2
Standard
70
0
40
0
41
1
50
0
71
0
42
2.5
3
txt
4
0
ENDTAB
0
ENDSEC
0
SECTION
2
ENTITIES
0
ENDSEC
0
EOF
@@ -0,0 +1,972 @@
0
SECTION
2
HEADER
9
$ACADVER
1
AC1032
9
$DWGCODEPAGE
3
ANSI_1252
9
$INSBASE
10
0
20
0
30
0
9
$EXTMIN
10
0
20
0
30
0
9
$EXTMAX
10
200
20
100
30
0
9
$LIMMIN
10
0
20
0
9
$LIMMAX
10
200
20
100
9
$LWDISPLAY
290
1
9
$INSUNITS
70
4
9
$MEASUREMENT
70
1
9
$HANDSEED
5
36
0
ENDSEC
0
SECTION
2
CLASSES
0
CLASS
1
ACDBDICTIONARYWDFLT
2
AcDbDictionaryWithDefault
3
ObjectDBX Classes
90
0
91
0
280
0
281
0
0
CLASS
1
ACDBPLACEHOLDER
2
AcDbPlaceHolder
3
ObjectDBX Classes
90
0
91
0
280
0
281
0
0
CLASS
1
LAYOUT
2
AcDbLayout
3
ObjectDBX Classes
90
0
91
0
280
0
281
0
0
ENDSEC
0
SECTION
2
TABLES
0
TABLE
2
VPORT
5
8
330
0
100
AcDbSymbolTable
70
1
0
VPORT
5
15
330
8
100
AcDbSymbolTableRecord
100
AcDbViewportTableRecord
2
*Active
70
0
10
0
20
0
11
1
21
1
12
100
22
50
13
0
23
0
14
1
24
1
15
10
25
10
16
0
26
0
36
1
17
0
27
0
37
0
40
146.666667
41
1.5
42
50
43
0
44
0
50
0
51
0
71
0
72
1000
73
1
74
3
75
0
76
0
77
0
78
0
281
0
65
0
146
0
0
ENDTAB
0
TABLE
2
LTYPE
5
2
330
0
100
AcDbSymbolTable
70
3
0
LTYPE
5
30
330
2
100
AcDbSymbolTableRecord
100
AcDbLinetypeTableRecord
2
ByBlock
70
0
3
72
65
73
0
40
0
0
LTYPE
5
31
330
2
100
AcDbSymbolTableRecord
100
AcDbLinetypeTableRecord
2
ByLayer
70
0
3
72
65
73
0
40
0
0
LTYPE
5
32
330
2
100
AcDbSymbolTableRecord
100
AcDbLinetypeTableRecord
2
Continuous
70
0
3
Solid line
72
65
73
0
40
0
0
ENDTAB
0
TABLE
2
LAYER
5
1
330
0
100
AcDbSymbolTable
70
2
0
LAYER
5
33
330
1
100
AcDbSymbolTableRecord
100
AcDbLayerTableRecord
2
0
70
0
62
7
6
Continuous
290
1
370
-3
390
1B
0
LAYER
5
34
330
1
100
AcDbSymbolTableRecord
100
AcDbLayerTableRecord
2
Layer1
70
0
62
1
6
Continuous
290
1
370
-3
390
1B
0
ENDTAB
0
TABLE
2
STYLE
5
5
330
0
100
AcDbSymbolTable
70
1
0
STYLE
5
35
330
5
100
AcDbSymbolTableRecord
100
AcDbTextStyleTableRecord
2
Standard
70
0
40
0
41
1
50
0
71
0
42
2.5
3
txt
4
0
ENDTAB
0
TABLE
2
VIEW
5
7
330
0
100
AcDbSymbolTable
70
0
0
ENDTAB
0
TABLE
2
UCS
5
6
330
0
100
AcDbSymbolTable
70
0
0
ENDTAB
0
TABLE
2
APPID
5
3
330
0
100
AcDbSymbolTable
70
1
0
APPID
5
16
330
3
100
AcDbSymbolTableRecord
100
AcDbRegAppTableRecord
2
ACAD
70
0
0
ENDTAB
0
TABLE
2
DIMSTYLE
5
4
330
0
100
AcDbSymbolTable
70
1
100
AcDbDimStyleTable
0
DIMSTYLE
105
17
330
4
100
AcDbSymbolTableRecord
100
AcDbDimStyleTableRecord
2
Standard
70
0
0
ENDTAB
0
TABLE
2
BLOCK_RECORD
5
9
330
0
100
AcDbSymbolTable
70
2
0
BLOCK_RECORD
5
D
330
9
100
AcDbSymbolTableRecord
100
AcDbBlockTableRecord
2
*Model_Space
340
13
70
0
280
1
281
0
0
BLOCK_RECORD
5
E
330
9
100
AcDbSymbolTableRecord
100
AcDbBlockTableRecord
2
*Paper_Space
340
14
70
0
280
1
281
0
0
ENDTAB
0
ENDSEC
0
SECTION
2
BLOCKS
0
BLOCK
5
F
330
D
100
AcDbEntity
8
0
100
AcDbBlockBegin
2
*Model_Space
70
0
10
0
20
0
30
0
3
*Model_Space
1
0
ENDBLK
5
10
330
D
100
AcDbEntity
8
0
100
AcDbBlockEnd
0
BLOCK
5
11
330
E
100
AcDbEntity
8
0
100
AcDbBlockBegin
2
*Paper_Space
70
0
10
0
20
0
30
0
3
*Paper_Space
1
0
ENDBLK
5
12
330
E
100
AcDbEntity
8
0
100
AcDbBlockEnd
0
ENDSEC
0
SECTION
2
ENTITIES
0
ENDSEC
0
SECTION
2
OBJECTS
0
DICTIONARY
5
A
330
0
100
AcDbDictionary
281
1
3
ACAD_GROUP
350
B
3
ACAD_LAYOUT
350
C
3
ACAD_PLOTSTYLENAME
350
1A
0
DICTIONARY
5
B
330
A
100
AcDbDictionary
281
1
0
DICTIONARY
5
C
330
A
100
AcDbDictionary
281
1
3
Layout1
350
14
3
Model
350
13
0
ACDBDICTIONARYWDFLT
5
1A
330
A
100
AcDbDictionary
281
1
3
Normal
350
1B
100
AcDbDictionaryWithDefault
340
1B
0
ACDBPLACEHOLDER
5
1B
330
1A
0
LAYOUT
5
13
330
C
100
AcDbPlotSettings
1
2
none_device
4
6
40
0
41
0
42
0
43
0
44
0
45
0
46
0
47
0
48
0
49
0
140
0
141
0
142
1
143
1
70
1712
72
1
73
0
74
5
7
75
16
76
0
77
2
78
300
147
1
148
0
149
0
100
AcDbLayout
1
Model
70
1
71
0
10
0
20
0
11
200
21
100
12
0
22
0
32
0
14
0
24
0
34
0
15
200
25
100
35
0
146
0
13
0
23
0
33
0
16
1
26
0
36
0
17
0
27
1
37
0
76
1
330
D
0
LAYOUT
5
14
330
C
100
AcDbPlotSettings
1
2
none_device
4
6
40
0
41
0
42
0
43
0
44
0
45
0
46
0
47
0
48
0
49
0
140
0
141
0
142
1
143
1
70
688
72
1
73
0
74
5
7
75
16
76
0
77
2
78
300
147
1
148
0
149
0
100
AcDbLayout
1
Layout1
70
1
71
1
10
0
20
0
11
200
21
100
12
0
22
0
32
0
14
0
24
0
34
0
15
200
25
100
35
0
146
0
13
0
23
0
33
0
16
1
26
0
36
0
17
0
27
1
37
0
76
1
330
E
0
ENDSEC
0
EOF
+268
View File
@@ -0,0 +1,268 @@
0
SECTION
2
HEADER
9
$ACADVER
1
AC1009
9
$DWGCODEPAGE
3
ANSI_1252
9
$INSBASE
10
0
20
0
30
0
9
$EXTMIN
10
0
20
0
30
0
9
$EXTMAX
10
200
20
100
30
0
9
$LIMMIN
10
0
20
0
9
$LIMMAX
10
200
20
100
0
ENDSEC
0
SECTION
2
TABLES
0
TABLE
2
VPORT
70
1
0
VPORT
2
*ACTIVE
70
0
10
0
20
0
11
1
21
1
12
100
22
50
13
0
23
0
14
1
24
1
15
10
25
10
16
0
26
0
36
1
17
0
27
0
37
0
40
146.666667
41
1.5
42
50
43
0
44
0
50
0
51
0
71
0
72
1000
73
1
74
3
75
0
76
0
77
0
78
0
0
ENDTAB
0
TABLE
2
LTYPE
70
3
0
LTYPE
2
ByBlock
70
0
3
72
65
73
0
40
0
0
LTYPE
2
ByLayer
70
0
3
72
65
73
0
40
0
0
LTYPE
2
Continuous
70
0
3
Solid line
72
65
73
0
40
0
0
ENDTAB
0
TABLE
2
LAYER
70
2
0
LAYER
2
0
70
0
62
7
6
Continuous
0
LAYER
2
Layer1
70
0
62
1
6
Continuous
0
ENDTAB
0
TABLE
2
STYLE
70
1
0
STYLE
2
Standard
70
0
40
0
41
1
50
0
71
0
42
2.5
3
txt
4
0
ENDTAB
0
ENDSEC
0
SECTION
2
ENTITIES
0
LINE
8
Layer1
62
1
10
0
20
0
30
0
11
10
21
20
31
0
0
ENDSEC
0
EOF
@@ -0,0 +1,982 @@
0
SECTION
2
HEADER
9
$ACADVER
1
AC1015
9
$DWGCODEPAGE
3
ANSI_1252
9
$INSBASE
10
0
20
0
30
0
9
$EXTMIN
10
0
20
0
30
0
9
$EXTMAX
10
200
20
100
30
0
9
$LIMMIN
10
0
20
0
9
$LIMMAX
10
200
20
100
9
$LWDISPLAY
290
1
9
$INSUNITS
70
4
9
$MEASUREMENT
70
1
9
$HANDSEED
5
37
0
ENDSEC
0
SECTION
2
CLASSES
0
CLASS
1
ACDBDICTIONARYWDFLT
2
AcDbDictionaryWithDefault
3
ObjectDBX Classes
90
0
280
0
281
0
0
CLASS
1
ACDBPLACEHOLDER
2
AcDbPlaceHolder
3
ObjectDBX Classes
90
0
280
0
281
0
0
CLASS
1
LAYOUT
2
AcDbLayout
3
ObjectDBX Classes
90
0
280
0
281
0
0
ENDSEC
0
SECTION
2
TABLES
0
TABLE
2
VPORT
5
8
330
0
100
AcDbSymbolTable
70
1
0
VPORT
5
15
330
8
100
AcDbSymbolTableRecord
100
AcDbViewportTableRecord
2
*Active
70
0
10
0
20
0
11
1
21
1
12
100
22
50
13
0
23
0
14
1
24
1
15
10
25
10
16
0
26
0
36
1
17
0
27
0
37
0
40
146.666667
41
1.5
42
50
43
0
44
0
50
0
51
0
71
0
72
1000
73
1
74
3
75
0
76
0
77
0
78
0
281
0
65
0
146
0
0
ENDTAB
0
TABLE
2
LTYPE
5
2
330
0
100
AcDbSymbolTable
70
3
0
LTYPE
5
31
330
2
100
AcDbSymbolTableRecord
100
AcDbLinetypeTableRecord
2
ByBlock
70
0
3
72
65
73
0
40
0
0
LTYPE
5
32
330
2
100
AcDbSymbolTableRecord
100
AcDbLinetypeTableRecord
2
ByLayer
70
0
3
72
65
73
0
40
0
0
LTYPE
5
33
330
2
100
AcDbSymbolTableRecord
100
AcDbLinetypeTableRecord
2
Continuous
70
0
3
Solid line
72
65
73
0
40
0
0
ENDTAB
0
TABLE
2
LAYER
5
1
330
0
100
AcDbSymbolTable
70
2
0
LAYER
5
34
330
1
100
AcDbSymbolTableRecord
100
AcDbLayerTableRecord
2
0
70
0
62
7
6
Continuous
290
1
370
-3
390
1B
0
LAYER
5
35
330
1
100
AcDbSymbolTableRecord
100
AcDbLayerTableRecord
2
Layer1
70
0
62
1
6
Continuous
290
1
370
-3
390
1B
0
ENDTAB
0
TABLE
2
STYLE
5
5
330
0
100
AcDbSymbolTable
70
1
0
STYLE
5
36
330
5
100
AcDbSymbolTableRecord
100
AcDbTextStyleTableRecord
2
Standard
70
0
40
0
41
1
50
0
71
0
42
2.5
3
txt
4
0
ENDTAB
0
TABLE
2
VIEW
5
7
330
0
100
AcDbSymbolTable
70
0
0
ENDTAB
0
TABLE
2
UCS
5
6
330
0
100
AcDbSymbolTable
70
0
0
ENDTAB
0
TABLE
2
APPID
5
3
330
0
100
AcDbSymbolTable
70
1
0
APPID
5
16
330
3
100
AcDbSymbolTableRecord
100
AcDbRegAppTableRecord
2
ACAD
70
0
0
ENDTAB
0
TABLE
2
DIMSTYLE
5
4
330
0
100
AcDbSymbolTable
70
1
100
AcDbDimStyleTable
0
DIMSTYLE
105
17
330
4
100
AcDbSymbolTableRecord
100
AcDbDimStyleTableRecord
2
Standard
70
0
0
ENDTAB
0
TABLE
2
BLOCK_RECORD
5
9
330
0
100
AcDbSymbolTable
70
2
0
BLOCK_RECORD
5
D
330
9
100
AcDbSymbolTableRecord
100
AcDbBlockTableRecord
2
*Model_Space
340
13
70
0
280
1
281
0
0
BLOCK_RECORD
5
E
330
9
100
AcDbSymbolTableRecord
100
AcDbBlockTableRecord
2
*Paper_Space
340
14
70
0
280
1
281
0
0
ENDTAB
0
ENDSEC
0
SECTION
2
BLOCKS
0
BLOCK
5
F
330
D
100
AcDbEntity
8
0
100
AcDbBlockBegin
2
*Model_Space
70
0
10
0
20
0
30
0
3
*Model_Space
1
0
ENDBLK
5
10
330
D
100
AcDbEntity
8
0
100
AcDbBlockEnd
0
BLOCK
5
11
330
E
100
AcDbEntity
8
0
100
AcDbBlockBegin
2
*Paper_Space
70
0
10
0
20
0
30
0
3
*Paper_Space
1
0
ENDBLK
5
12
330
E
100
AcDbEntity
8
0
100
AcDbBlockEnd
0
ENDSEC
0
SECTION
2
ENTITIES
0
LINE
5
30
330
D
100
AcDbEntity
8
Layer1
62
1
370
25
100
AcDbLine
10
0
20
0
30
0
11
10
21
20
31
0
0
ENDSEC
0
SECTION
2
OBJECTS
0
DICTIONARY
5
A
330
0
100
AcDbDictionary
281
1
3
ACAD_GROUP
350
B
3
ACAD_LAYOUT
350
C
3
ACAD_PLOTSTYLENAME
350
1A
0
DICTIONARY
5
B
330
A
100
AcDbDictionary
281
1
0
DICTIONARY
5
C
330
A
100
AcDbDictionary
281
1
3
Layout1
350
14
3
Model
350
13
0
ACDBDICTIONARYWDFLT
5
1A
330
A
100
AcDbDictionary
281
1
3
Normal
350
1B
100
AcDbDictionaryWithDefault
340
1B
0
ACDBPLACEHOLDER
5
1B
330
1A
0
LAYOUT
5
13
330
C
100
AcDbPlotSettings
1
2
none_device
4
6
40
0
41
0
42
0
43
0
44
0
45
0
46
0
47
0
48
0
49
0
140
0
141
0
142
1
143
1
70
1712
72
1
73
0
74
5
7
75
16
147
1
148
0
149
0
100
AcDbLayout
1
Model
70
1
71
0
10
0
20
0
11
200
21
100
12
0
22
0
32
0
14
0
24
0
34
0
15
200
25
100
35
0
146
0
13
0
23
0
33
0
16
1
26
0
36
0
17
0
27
1
37
0
76
1
330
D
0
LAYOUT
5
14
330
C
100
AcDbPlotSettings
1
2
none_device
4
6
40
0
41
0
42
0
43
0
44
0
45
0
46
0
47
0
48
0
49
0
140
0
141
0
142
1
143
1
70
688
72
1
73
0
74
5
7
75
16
147
1
148
0
149
0
100
AcDbLayout
1
Layout1
70
1
71
1
10
0
20
0
11
200
21
100
12
0
22
0
32
0
14
0
24
0
34
0
15
200
25
100
35
0
146
0
13
0
23
0
33
0
16
1
26
0
36
0
17
0
27
1
37
0
76
1
330
E
0
ENDSEC
0
EOF
File diff suppressed because it is too large Load Diff
+3
View File
@@ -18,6 +18,9 @@
//! - [`stream`]: one flat scan-line part read block by block, for pictures larger than memory.
//! - [`cryptomatte_samples`]: a file's Cryptomatte layers and their per-pixel (ID, coverage) ranks.
/// RFC 1950/1951 compressor for ZIP-compressed EXR chunks.
pub mod zlib;
pub mod channels;
pub mod cryptomatte;
#[cfg(feature = "decode")]
+795
View File
@@ -0,0 +1,795 @@
//! A small DEFLATE encoder (RFC 1951) in a zlib wrapper (RFC 1950), written from the RFCs for the
//! ZIP-compressed OpenEXR chunks.
//!
//! Greedy LZ77 over a 32 KB window (hash chains of bounded length), then each block of tokens is
//! written as whichever of stored, fixed-Huffman or dynamic-Huffman is smallest. Huffman code
//! lengths are limited (15 bits, 7 for the code-length code) by halving the symbol frequencies
//! until the tree fits. Every code has at least two symbols, so all codes are complete. The
//! output favours simplicity and correctness over ratio; worst-case expansion is the stored-block
//! overhead (5 bytes per 64 KB).
use std::cmp::Reverse;
use std::collections::BinaryHeap;
const WINDOW: usize = 32 * 1024;
const MIN_MATCH: usize = 3;
const MAX_MATCH: usize = 258;
/// Hash chain candidates tried per position.
const MAX_CHAIN: usize = 48;
/// Tokens per block (a new set of Huffman codes after this many).
const BLOCK_TOKENS: usize = 1 << 15;
const MAX_STORED: usize = 65_535;
const LEN_BASE: [u16; 29] = [3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 19, 23, 27, 31, 35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258];
const LEN_EXTRA: [u8; 29] = [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0];
const DIST_BASE: [u16; 30] =
[1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193, 257, 385, 513, 769, 1025, 1537, 2049, 3073, 4097, 6145, 8193, 12289, 16385, 24577];
const DIST_EXTRA: [u8; 30] = [0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13];
/// Order in which the code-length code's lengths are sent.
const CL_ORDER: [usize; 19] = [16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15];
/// `data` compressed as a zlib stream (CMF 0x78: deflate, 32 KB window). `tables` are the match
/// finder's hash tables, kept by the caller across the chunks of a picture; the output does not
/// depend on what they held before.
pub fn zlib(data: &[u8], tables: &mut Tables) -> Vec<u8> {
let mut w = Bits { out: Vec::with_capacity(data.len() / 2 + 64), acc: 0, n: 0 };
w.out.extend_from_slice(&[0x78, 0x9C]); // (0x78 << 8 | 0x9C) % 31 == 0
deflate(data, &mut w, tables);
w.align();
w.out.extend_from_slice(&adler32(data).to_be_bytes());
w.out
}
/// Adler-32 (RFC 1950 §9); 5552 bytes is the longest run that cannot overflow the sums.
fn adler32(data: &[u8]) -> u32 {
let (mut a, mut b) = (1_u32, 0_u32);
for c in data.chunks(5552) {
for &x in c {
a += u32::from(x);
b += a;
}
a %= 65_521;
b %= 65_521;
}
(b << 16) | a
}
/// LSB-first bit writer.
struct Bits {
out: Vec<u8>,
acc: u64,
n: u32,
}
impl Bits {
/// The low `n` bits of `v` (n ≤ 32).
fn put(&mut self, v: u32, n: u32) {
let mask = (1_u64 << n) - 1;
self.acc |= (u64::from(v) & mask) << self.n;
self.n += n;
while self.n >= 8 {
self.out.push(self.acc as u8);
self.acc >>= 8;
self.n -= 8;
}
}
fn align(&mut self) {
if self.n > 0 {
self.out.push(self.acc as u8);
}
self.acc = 0;
self.n = 0;
}
}
#[derive(Clone, Copy)]
enum Tok {
Lit(u8),
Match { len: u16, dist: u16 },
}
/// Index into [`LEN_BASE`] of a match length (3..=258).
fn len_code(len: u16) -> usize {
LEN_BASE.partition_point(|&b| b <= len).saturating_sub(1)
}
/// Index into [`DIST_BASE`] of a distance (1..=32768).
fn dist_code(dist: u16) -> usize {
DIST_BASE.partition_point(|&b| b <= dist).saturating_sub(1)
}
/// The match finder's hash heads and chains, reused from one input to the next.
///
/// A slot holds `base + p + 1` for position `p` of the input that wrote it; anything at or below
/// the current input's `base` was left by an earlier input and reads as empty. So the tables are
/// never cleared between inputs: an OpenEXR ZIPS frame is one input per scan line, and zeroing
/// 256 KiB of tables for each 23 KB UHD line cost more memory traffic than the data itself.
#[derive(Default)]
pub struct Tables {
head: Vec<u32>,
prev: Vec<u32>,
/// Bytes compressed through these tables since they were last cleared.
base: u32,
}
/// LZ77 match finder: hash heads and chains over the window.
struct Matcher<'a> {
data: &'a [u8],
head: &'a mut [u32],
prev: &'a mut [u32],
bits: u32,
/// `prev` slots used by this input, minus one (a power of two minus one).
mask: usize,
base: u32,
}
impl<'a> Matcher<'a> {
/// A matcher over `data` (shorter than `u32::MAX` bytes), or None when it is not.
fn new(data: &'a [u8], t: &'a mut Tables) -> Option<Self> {
// hash width and chain span follow the input's size, as they did when every input had
// tables of its own (the output depends on them), so short chunks stay cheap to hash
let span = data.len().clamp(256, WINDOW).next_power_of_two();
let bits = span.trailing_zeros().clamp(8, 15);
let n = u32::try_from(data.len()).ok().filter(|&n| n < u32::MAX)?;
if t.base.checked_add(n).and_then(|b| b.checked_add(1)).is_none() {
// positions would no longer fit after `base`: start over from empty tables
t.head.fill(0);
t.prev.fill(0);
t.base = 0;
}
// grown slots are 0, which is never above `base`, so they read as empty
if t.head.len() < 1 << bits {
t.head.resize(1 << bits, 0);
}
if t.prev.len() < span {
t.prev.resize(span, 0);
}
let base = t.base;
t.base += n;
let (head, prev) = (t.head.get_mut(..1 << bits)?, t.prev.get_mut(..span)?);
Some(Matcher { data, head, prev, bits, mask: span - 1, base })
}
/// Position `p` of this input from a stored slot, or None for an empty or earlier input's slot.
fn pos(&self, slot: u32) -> Option<usize> {
slot.checked_sub(self.base)?.checked_sub(1).map(|p| p as usize)
}
fn hash(&self, p: usize) -> Option<usize> {
let b = self.data.get(p..p + MIN_MATCH)?;
let v = (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]);
Some((v.wrapping_mul(0x9E37_79B1) >> (32 - self.bits)) as usize)
}
/// Record position `p` (stored as `p + 1`; 0 = empty).
fn insert(&mut self, p: usize) {
let Some(h) = self.hash(p) else { return };
let (Some(head), Ok(p32)) = (self.head.get(h).copied(), u32::try_from(p)) else { return };
if let Some(slot) = self.prev.get_mut(p & self.mask) {
*slot = head;
}
if let Some(slot) = self.head.get_mut(h) {
// `new` reserved `base + len + 1` within u32
*slot = self.base + p32 + 1;
}
}
/// The longest earlier match at `p`: (length, distance), length 0 if none.
fn longest(&self, p: usize) -> (usize, usize) {
let Some(h) = self.hash(p) else { return (0, 0) };
let max = self.data.len().saturating_sub(p).min(MAX_MATCH);
let Some(here) = self.data.get(p..p + max) else { return (0, 0) };
let (mut best, mut best_dist) = (0, 0);
let mut cand = self.head.get(h).and_then(|&s| self.pos(s));
for _ in 0..MAX_CHAIN {
let Some(c) = cand else { break };
if c >= p || p - c > WINDOW {
break;
}
// a candidate that differs at `best` cannot be longer than `best`: skip comparing it
if best == 0 || self.data.get(c + best) == here.get(best) {
let l = self.data.get(c..).unwrap_or_default().iter().zip(here).take_while(|(a, b)| a == b).count();
if l > best {
(best, best_dist) = (l, p - c);
if l == max {
break;
}
}
}
let Some(next) = self.prev.get(c & self.mask).and_then(|&s| self.pos(s)) else { break };
// chains only go back; anything else is a stale slot
if next >= c {
break;
}
cand = Some(next);
}
(best, best_dist)
}
}
/// The deflate blocks of `data`, the last one final.
fn deflate(data: &[u8], w: &mut Bits, tables: &mut Tables) {
if data.is_empty() {
// a final fixed-Huffman block holding only end-of-block (code 0000000)
w.put(1, 1);
w.put(1, 2);
w.put(0, 7);
return;
}
// positions are kept in u32; longer inputs (never an OpenEXR chunk) go out stored
let mut m = Matcher::new(data, tables);
let mut toks = Vec::with_capacity(BLOCK_TOKENS.min(data.len()) + 1);
let (mut start, mut i) = (0, 0);
while i < data.len() {
let (len, dist) = m.as_ref().map_or((0, 0), |m| m.longest(i));
let step = if len >= MIN_MATCH {
toks.push(Tok::Match { len: len as u16, dist: dist as u16 });
len
} else {
toks.push(Tok::Lit(data[i]));
1
};
if let Some(m) = m.as_mut() {
for p in i..i + step {
m.insert(p);
}
}
i += step;
if toks.len() >= BLOCK_TOKENS || i == data.len() {
block(w, &toks, &data[start..i], i == data.len());
toks.clear();
start = i;
}
}
}
/// Bits the tokens take with the given code lengths (EOB included).
fn data_bits(lf: &[u32], df: &[u32], ll: &[u8], dl: &[u8]) -> u64 {
let mut n = 0_u64;
for (s, (&f, &l)) in lf.iter().zip(ll).enumerate() {
let extra = s.checked_sub(257).and_then(|k| LEN_EXTRA.get(k)).copied().unwrap_or(0);
n += u64::from(f) * u64::from(l + extra);
}
for (d, (&f, &l)) in df.iter().zip(dl).enumerate() {
n += u64::from(f) * u64::from(l + DIST_EXTRA.get(d).copied().unwrap_or(0));
}
n
}
/// One block (split into several stored blocks when stored is smallest and `raw` is long).
fn block(w: &mut Bits, toks: &[Tok], raw: &[u8], last: bool) {
let mut lf = [0_u32; 286];
let mut df = [0_u32; 30];
for t in toks {
match *t {
Tok::Lit(b) => lf[b as usize] += 1,
Tok::Match { len, dist } => {
lf[257 + len_code(len)] += 1;
df[dist_code(dist)] += 1;
}
}
}
lf[256] += 1;
// dynamic codes and their header
let ll = lengths(&lf, 15);
let dl = lengths(&df, 15);
let hlit = ll.iter().rposition(|&l| l > 0).map_or(257, |p| (p + 1).max(257));
let hdist = dl.iter().rposition(|&l| l > 0).map_or(1, |p| p + 1);
let seq = rle_lengths(&[&ll[..hlit], &dl[..hdist]].concat());
let mut cf = [0_u32; 19];
for &(s, _) in &seq {
cf[s as usize] += 1;
}
let cl = lengths(&cf, 7);
let hclen = CL_ORDER.iter().rposition(|&s| cl[s] > 0).map_or(4, |p| (p + 1).max(4));
let seq_bits: u64 =
seq.iter().map(|&(s, _)| u64::from(cl[s as usize]) + [2_u64, 3, 7].get((s as usize).wrapping_sub(16)).copied().unwrap_or(0)).sum();
let dyn_bits = 3 + 14 + 3 * hclen as u64 + seq_bits + data_bits(&lf, &df, &ll, &dl);
let (fll, fdl) = fixed_lengths();
let fixed_bits = 3 + data_bits(&lf, &df, &fll, &fdl);
// per stored piece: header, at most 7 padding bits, LEN and NLEN
let pieces = raw.len().div_ceil(MAX_STORED).max(1) as u64;
let stored_bits = pieces * (3 + 7 + 32) + 8 * raw.len() as u64;
if stored_bits <= fixed_bits.min(dyn_bits) {
let n = raw.chunks(MAX_STORED).count();
for (k, piece) in raw.chunks(MAX_STORED).enumerate() {
w.put(u32::from(last && k + 1 == n), 1);
w.put(0, 2);
w.align();
let len = piece.len() as u16;
w.out.extend_from_slice(&len.to_le_bytes());
w.out.extend_from_slice(&(!len).to_le_bytes());
w.out.extend_from_slice(piece);
}
return;
}
w.put(u32::from(last), 1);
if fixed_bits <= dyn_bits {
w.put(1, 2);
write_tokens(w, toks, &fll, &fdl);
return;
}
w.put(2, 2);
w.put((hlit - 257) as u32, 5);
w.put((hdist - 1) as u32, 5);
w.put((hclen - 4) as u32, 4);
for &s in &CL_ORDER[..hclen] {
w.put(u32::from(cl[s]), 3);
}
let cc = codes(&cl);
for &(s, x) in &seq {
w.put(u32::from(cc[s as usize]), u32::from(cl[s as usize]));
match s {
16 => w.put(u32::from(x), 2),
17 => w.put(u32::from(x), 3),
18 => w.put(u32::from(x), 7),
_ => {}
}
}
write_tokens(w, toks, &ll, &dl);
}
/// The fixed Huffman code lengths (RFC 1951 §3.2.6).
fn fixed_lengths() -> ([u8; 288], [u8; 30]) {
let mut ll = [8_u8; 288];
ll[144..256].fill(9);
ll[256..280].fill(7);
(ll, [5; 30])
}
fn write_tokens(w: &mut Bits, toks: &[Tok], ll: &[u8], dl: &[u8]) {
let lc = codes(ll);
let dc = codes(dl);
let sym = |w: &mut Bits, s: usize| w.put(u32::from(lc[s]), u32::from(ll[s]));
for t in toks {
match *t {
Tok::Lit(b) => sym(w, b as usize),
Tok::Match { len, dist } => {
let k = len_code(len);
sym(w, 257 + k);
w.put(u32::from(len - LEN_BASE[k]), u32::from(LEN_EXTRA[k]));
let d = dist_code(dist);
w.put(u32::from(dc[d]), u32::from(dl[d]));
w.put(u32::from(dist - DIST_BASE[d]), u32::from(DIST_EXTRA[d]));
}
}
}
sym(w, 256);
}
/// Canonical Huffman codes for `lens`, bit-reversed for the LSB-first writer.
fn codes(lens: &[u8]) -> Vec<u16> {
let mut count = [0_u32; 16];
for &l in lens {
if (1..16).contains(&l) {
count[l as usize] += 1;
}
}
let mut next = [0_u32; 16];
let mut code = 0;
for bits in 1..16 {
code = (code + count[bits - 1]) << 1;
next[bits] = code;
}
lens.iter()
.map(|&l| {
if !(1..16).contains(&l) {
return 0;
}
let c = next[l as usize];
next[l as usize] += 1;
(c.reverse_bits() >> (32 - u32::from(l))) as u16
})
.collect()
}
/// Code lengths for `freq`, none longer than `limit`; at least two symbols always get a code.
fn lengths(freq: &[u32], limit: u8) -> Vec<u8> {
let mut f: Vec<u64> = freq.iter().map(|&x| u64::from(x)).collect();
let mut used = f.iter().filter(|&&x| x > 0).count();
for x in f.iter_mut() {
if used >= 2 {
break;
}
if *x == 0 {
*x = 1;
used += 1;
}
}
// halving converges: once every used frequency is 1 the tree is balanced (depth ≤ 9 here)
for _ in 0..66 {
let l = huffman(&f);
if l.iter().all(|&d| d <= limit) {
return l;
}
for x in f.iter_mut().filter(|x| **x > 0) {
*x = (*x >> 1).max(1);
}
}
huffman(&f)
}
/// Huffman tree depths of the symbols with non-zero frequency (0 for the rest).
fn huffman(f: &[u64]) -> Vec<u8> {
let n = f.len();
let mut heap: BinaryHeap<Reverse<(u64, usize)>> = f.iter().enumerate().filter(|(_, w)| **w > 0).map(|(i, &w)| Reverse((w, i))).collect();
let mut parent = vec![usize::MAX; 2 * n];
let mut next = n;
while heap.len() > 1 {
let (Some(Reverse((wa, a))), Some(Reverse((wb, b)))) = (heap.pop(), heap.pop()) else { break };
parent[a] = next;
parent[b] = next;
heap.push(Reverse((wa + wb, next)));
next += 1;
}
// parents always come after their children, so walk down from the root
let mut depth = vec![0_u32; next];
for i in (0..next).rev() {
if let Some(&p) = parent.get(i).filter(|&&p| p < next) {
depth[i] = depth[p].saturating_add(1);
}
}
depth[..n].iter().map(|&d| d.min(u32::from(u8::MAX)) as u8).collect()
}
/// Code lengths run-length coded with the code-length alphabet: (symbol, extra-bits value).
fn rle_lengths(lens: &[u8]) -> Vec<(u8, u8)> {
let mut out = Vec::new();
let mut i = 0;
while i < lens.len() {
let l = lens[i];
let run = lens[i..].iter().take_while(|&&x| x == l).count();
let mut r = run;
if l == 0 {
while r >= 11 {
let k = r.min(138);
out.push((18, (k - 11) as u8));
r -= k;
}
if r >= 3 {
out.push((17, (r - 3) as u8));
r = 0;
}
} else {
out.push((l, 0));
r -= 1;
while r >= 3 {
let k = r.min(6);
out.push((16, (k - 3) as u8));
r -= k;
}
}
out.extend(std::iter::repeat_n((l, 0), r));
i += run;
}
out
}
#[cfg(test)]
mod tests {
use super::*;
/// A minimal inflater (RFC 1951), only to check the encoder; returns None on any error.
pub(crate) fn inflate(z: &[u8]) -> Option<Vec<u8>> {
let (cmf, flg) = (*z.first()?, *z.get(1)?);
if cmf & 0x0F != 8 || (u16::from(cmf) << 8 | u16::from(flg)) % 31 != 0 || flg & 0x20 != 0 {
return None;
}
let mut pos = 16_usize; // bit position
let bit = |pos: &mut usize| -> Option<u32> {
let b = (*z.get(*pos / 8)? >> (*pos % 8)) & 1;
*pos += 1;
Some(u32::from(b))
};
let bits = |pos: &mut usize, n: u32| -> Option<u32> {
let mut v = 0;
for k in 0..n {
v |= bit(pos)? << k;
}
Some(v)
};
// decode one symbol with canonical lengths (slow but simple)
let decode = |pos: &mut usize, lens: &[u8]| -> Option<usize> {
let (mut code, mut first, mut index) = (0_i32, 0_i32, 0_i32);
let mut count = [0_i32; 16];
for &l in lens {
count[l as usize] += 1;
}
let mut sorted: Vec<usize> = (0..lens.len()).filter(|&s| lens[s] > 0).collect();
sorted.sort_by_key(|&s| (lens[s], s));
for &c in count.iter().skip(1) {
code |= bit(pos)? as i32;
if code - c < first {
return sorted.get((index + code - first) as usize).copied();
}
index += c;
first = (first + c) << 1;
code <<= 1;
}
None
};
let mut out = Vec::new();
loop {
let last = bit(&mut pos)?;
match bits(&mut pos, 2)? {
0 => {
pos = pos.div_ceil(8) * 8;
let at = pos / 8;
let len = u16::from_le_bytes([*z.get(at)?, *z.get(at + 1)?]);
let nlen = u16::from_le_bytes([*z.get(at + 2)?, *z.get(at + 3)?]);
if len != !nlen {
return None;
}
out.extend_from_slice(z.get(at + 4..at + 4 + len as usize)?);
pos = (at + 4 + len as usize) * 8;
}
t @ (1 | 2) => {
let (ll, dl) = if t == 1 {
let (a, b) = fixed_lengths();
(a.to_vec(), b.to_vec())
} else {
let hlit = bits(&mut pos, 5)? as usize + 257;
let hdist = bits(&mut pos, 5)? as usize + 1;
let hclen = bits(&mut pos, 4)? as usize + 4;
let mut cl = [0_u8; 19];
for &s in &CL_ORDER[..hclen] {
cl[s] = bits(&mut pos, 3)? as u8;
}
let mut lens = Vec::new();
while lens.len() < hlit + hdist {
match decode(&mut pos, &cl)? {
s @ 0..=15 => lens.push(s as u8),
16 => {
let p = *lens.last()?;
lens.extend(std::iter::repeat_n(p, 3 + bits(&mut pos, 2)? as usize));
}
17 => lens.extend(std::iter::repeat_n(0, 3 + bits(&mut pos, 3)? as usize)),
_ => lens.extend(std::iter::repeat_n(0, 11 + bits(&mut pos, 7)? as usize)),
}
}
if lens.len() != hlit + hdist {
return None;
}
(lens[..hlit].to_vec(), lens[hlit..].to_vec())
};
loop {
let s = decode(&mut pos, &ll)?;
if s < 256 {
out.push(s as u8);
} else if s == 256 {
break;
} else {
let k = s - 257;
let len = *LEN_BASE.get(k)? as usize + bits(&mut pos, u32::from(LEN_EXTRA[k]))? as usize;
let d = decode(&mut pos, &dl)?;
let dist = *DIST_BASE.get(d)? as usize + bits(&mut pos, u32::from(DIST_EXTRA[d]))? as usize;
let from = out.len().checked_sub(dist)?;
for j in 0..len {
out.push(out[from + j]);
}
}
}
}
_ => return None,
}
if last == 1 {
break;
}
}
let at = pos.div_ceil(8);
let sum = u32::from_be_bytes(z.get(at..at + 4)?.try_into().ok()?);
(sum == adler32(&out) && at + 4 == z.len()).then_some(out)
}
/// A deterministic pseudo-random byte stream.
fn noise(n: usize, seed: u32) -> Vec<u8> {
let mut s = seed | 1;
(0..n)
.map(|_| {
s ^= s << 13;
s ^= s >> 17;
s ^= s << 5;
s as u8
})
.collect()
}
#[test]
fn round_trips() {
let mut cases: Vec<Vec<u8>> = vec![vec![], vec![7], vec![1, 2], vec![0; 1], vec![0; 300_000], b"abcabcabcabcabcabd".to_vec()];
cases.push(noise(100_000, 9)); // incompressible: stored blocks
cases.push(noise(70_000, 3).iter().map(|b| b % 4).collect()); // few symbols: dynamic
cases.push((0..200_000_u32).map(|i| ((i / 7) % 251) as u8).collect()); // long repeats
// text-like: a small vocabulary repeated at varying distances
let words: [&[u8]; 6] = [b"red ", b"green ", b"blue ", b"alpha ", b"half ", b"linear "];
cases.push(noise(40_000, 5).iter().flat_map(|b| words[*b as usize % 6].iter().copied()).collect());
// skewed frequencies: Huffman lengths beyond 15 before limiting
let mut fib = Vec::new();
let (mut a, mut b) = (1_usize, 1_usize);
for s in 0..25_u8 {
fib.extend(std::iter::repeat_n(s.wrapping_mul(37), a.min(200_000)));
(a, b) = (b, a + b);
}
let r = noise(fib.len() * 4, 11);
for i in (1..fib.len()).rev() {
let j = u32::from_le_bytes(r[i * 4..i * 4 + 4].try_into().unwrap()) as usize % (i + 1);
fib.swap(i, j);
}
cases.push(fib);
for (k, data) in cases.iter().enumerate() {
let z = zlib(data, &mut Tables::default());
assert_eq!(inflate(&z).as_deref(), Some(data.as_slice()), "case {k}");
// worst case: stored overhead only
assert!(z.len() <= data.len() + (data.len().div_ceil(BLOCK_TOKENS) + 1) * 5 + 6, "case {k}: {} > {}", z.len(), data.len());
}
// repetitive data actually compresses
assert!(zlib(&cases[4], &mut Tables::default()).len() < 2_000);
assert!(zlib(&cases[8], &mut Tables::default()).len() < 20_000);
}
#[test]
fn length_limits_hold() {
// Fibonacci frequencies give the deepest possible Huffman tree
let mut f = vec![0_u32; 286];
let (mut a, mut b) = (1_u32, 1_u32);
for x in f.iter_mut().take(30) {
*x = a;
(a, b) = (b, a.saturating_add(b));
}
let l = lengths(&f, 15);
assert!(l.iter().all(|&d| d <= 15));
// a complete code: Kraft sum exactly 1
let kraft: f64 = l.iter().filter(|&&d| d > 0).map(|&d| 0.5_f64.powi(i32::from(d))).sum();
assert!((kraft - 1.0).abs() < 1e-12);
// one used symbol still gets a two-symbol code
let l = lengths(&[0, 5, 0], 7);
assert_eq!(l.iter().filter(|&&d| d == 1).count(), 2);
}
#[test]
fn adler_matches_rfc_example() {
// the classic test vector for "Wikipedia"
assert_eq!(adler32(b"Wikipedia"), 0x11E6_0398);
assert_eq!(adler32(&[]), 1);
}
/// The match finder before #4659: tables of its own per input, every chain candidate compared
/// from its first byte.
struct OldMatcher<'a> {
data: &'a [u8],
head: Vec<u32>,
prev: Vec<u32>,
bits: u32,
}
impl<'a> OldMatcher<'a> {
/// Tables of its own, sized to `data`.
fn new(data: &'a [u8]) -> Self {
let span = data.len().clamp(256, WINDOW).next_power_of_two();
let bits = span.trailing_zeros().clamp(8, 15);
OldMatcher { data, head: vec![0; 1 << bits], prev: vec![0; span], bits }
}
/// The hash of the three bytes at `p`, None near the end.
fn hash(&self, p: usize) -> Option<usize> {
let b = self.data.get(p..p + MIN_MATCH)?;
let v = (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]);
Some((v.wrapping_mul(0x9E37_79B1) >> (32 - self.bits)) as usize)
}
/// Record position `p` (stored as `p + 1`; 0 = empty).
fn insert(&mut self, p: usize) {
let Some(h) = self.hash(p) else { return };
let mask = self.prev.len() - 1;
self.prev[p & mask] = self.head[h];
self.head[h] = p as u32 + 1;
}
/// The longest earlier match at `p`: (length, distance), length 0 if none.
fn longest(&self, p: usize) -> (usize, usize) {
let Some(h) = self.hash(p) else { return (0, 0) };
let max = (self.data.len() - p).min(MAX_MATCH);
let here = &self.data[p..p + max];
let mask = self.prev.len() - 1;
let (mut best, mut best_dist) = (0, 0);
let mut cand = self.head[h] as usize;
for _ in 0..MAX_CHAIN {
let Some(c) = cand.checked_sub(1) else { break };
if c >= p || p - c > WINDOW {
break;
}
let l = self.data[c..].iter().zip(here).take_while(|(a, b)| a == b).count();
if l > best {
(best, best_dist) = (l, p - c);
if l == max {
break;
}
}
let next = self.prev[c & mask] as usize;
if next == 0 || next > c {
break;
}
cand = next;
}
(best, best_dist)
}
}
/// Inputs shaped like OpenEXR chunks (predicted half-float scan lines, single and 16-line)
/// and the awkward cases: empty, tiny, incompressible, long runs, few symbols.
fn chunk_cases() -> Vec<Vec<u8>> {
let line: Vec<u8> = (0..23_040_u32).map(|i| (128 + ((i / 3) % 7) as i32 - 3 + (i % 5 == 0) as i32) as u8).collect();
let mut cases = vec![line.clone(), line.iter().rev().copied().collect(), vec![], vec![9], b"abcabcabcabd".to_vec()];
cases.push(line.iter().cycle().take(16 * 23_040).copied().collect()); // ZIP: 16 lines, longer than the window
cases.push(noise(23_040, 4));
cases.push(noise(70_000, 3).iter().map(|b| b % 4).collect());
cases.push(vec![0; 300_000]);
cases.push(line.clone());
cases.push(noise(300, 7));
cases
}
/// The matcher's greedy parse of `data`: what `deflate` codes.
fn parse<F: FnMut(usize) -> (usize, usize), G: FnMut(usize)>(data: &[u8], mut longest: F, mut insert: G) -> Vec<(usize, usize)> {
let (mut out, mut i) = (Vec::new(), 0);
while i < data.len() {
let (len, dist) = longest(i);
let step = if len >= MIN_MATCH { len } else { 1 };
out.push(if len >= MIN_MATCH { (len, dist) } else { (0, 0) });
for p in i..i + step {
insert(p);
}
i += step;
}
out
}
/// Shared tables and the candidate skip find exactly the matches the previous matcher found.
#[test]
fn shared_tables_find_the_matches_the_old_per_chunk_tables_found() {
let mut tables = Tables::default();
for (k, data) in chunk_cases().iter().enumerate() {
let old = std::cell::RefCell::new(OldMatcher::new(data));
let want = parse(data, |p| old.borrow().longest(p), |p| old.borrow_mut().insert(p));
let new = std::cell::RefCell::new(Matcher::new(data, &mut tables).expect("fits"));
let got = parse(data, |p| new.borrow().longest(p), |p| new.borrow_mut().insert(p));
assert!(got == want, "chunk {k}: the parse differs");
}
}
/// Shared tables compress to the bytes fresh ones give, also when positions run out and they start over.
#[test]
fn shared_tables_give_the_bytes_of_fresh_ones() {
let mut shared = Tables::default();
for (k, data) in chunk_cases().iter().enumerate() {
let z = zlib(data, &mut shared);
assert!(z == zlib(data, &mut Tables::default()), "chunk {k}");
assert_eq!(inflate(&z).as_deref(), Some(data.as_slice()), "chunk {k}");
}
// positions about to run past u32: the tables start over and the bytes stay the same
for gap in [0_u32, 1, 2, 23_040, 23_041, 1 << 20] {
shared.base = u32::MAX - gap;
for (k, data) in chunk_cases().iter().enumerate() {
assert!(zlib(data, &mut shared) == zlib(data, &mut Tables::default()), "gap {gap}, chunk {k}");
}
}
}
/// Later chunks use the same tables instead of allocating new ones.
#[test]
fn the_tables_are_reused_across_chunks() {
let mut tables = Tables::default();
let line = &chunk_cases()[0];
zlib(line, &mut tables);
let (head, prev) = (tables.head.as_ptr(), tables.prev.as_ptr());
for _ in 0..4 {
zlib(line, &mut tables);
assert!(tables.head.as_ptr() == head && tables.prev.as_ptr() == prev, "a chunk allocated new tables");
}
assert_eq!(tables.base as usize, 5 * line.len());
}
}
+14
View File
@@ -0,0 +1,14 @@
[package]
name = "craft-gzip"
description = "Streaming gzip writer with stored and compressed segments"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
flate2 = { version = "1", default-features = false, features = ["rust_backend"] }
+119
View File
@@ -0,0 +1,119 @@
//! Streaming gzip output with optional stored segments.
//!
//! Copyright (c) 2026 ArtCraft Team and the VectorCraft contributors.
//! Extracted from VectorCraft, licensed under MIT OR Apache-2.0.
//!
//! `flush` does not emit a deflate block; call [`Gz::finish`] to complete and flush the
//! stream. After an I/O error, discard the writer: the output may be incomplete.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
use flate2::{Compress, Compression, Crc, FlushCompress, Status};
use std::io::{self, Write};
/// Bytes of compressed output gathered before they go to the writer.
const OUT_CHUNK: usize = 64 << 10;
/// A gzip stream, written as [`flate2::write::GzEncoder`] at the default level writes it (the
/// same header and the same data; the deflate blocks are the same too where flate2 deflates with
/// miniz_oxide, not with zlib-rs, which writes them by how the data is fed), except that data which
/// is compressed already ([`Gz::packed`]) is stored as it is: the default level spends a second
/// or more per photo on it for next to nothing, and makes it slower to unpack. Where the level
/// changes the deflate blocks so far end with a sync flush and a fresh compressor writes on,
/// which makes one valid deflate stream that every reader unpacks.
pub struct Gz<W: Write> {
out: W,
deflate: Compress,
/// What `deflate` writes: stored blocks (packed data), else the default level.
stored: bool,
crc: Crc,
buf: Vec<u8>,
/// Bytes written (unpacked).
total: u64,
}
impl<W: Write> Gz<W> {
/// Write a gzip header and construct a writer.
pub fn new(mut out: W) -> io::Result<Self> {
// flate2's header for the default level: no name, no time, unknown OS.
out.write_all(&[0x1f, 0x8b, 8, 0, 0, 0, 0, 0, 0, 255])?;
Ok(Self {
out,
deflate: Compress::new(Compression::default(), false),
stored: false,
crc: Crc::new(),
buf: Vec::with_capacity(OUT_CHUNK),
total: 0,
})
}
/// Run the compressor over `input` with `flush` until it has taken it all (and, flushing,
/// written everything out).
fn deflate(&mut self, mut input: &[u8], flush: FlushCompress) -> io::Result<()> {
loop {
if self.buf.len() == self.buf.capacity() {
self.out.write_all(&self.buf)?;
self.buf.clear();
}
let (before_in, before_out) = (self.deflate.total_in(), self.deflate.total_out());
let status = self.deflate.compress_vec(input, &mut self.buf, flush).map_err(io::Error::other)?;
let taken = usize::try_from(self.deflate.total_in() - before_in).unwrap_or(input.len()).min(input.len());
input = input.get(taken..).unwrap_or_default();
let made = self.deflate.total_out() - before_out;
let full = self.buf.len() == self.buf.capacity();
match flush {
FlushCompress::None if input.is_empty() => return Ok(()),
FlushCompress::Finish if status == Status::StreamEnd => return Ok(()),
// A flush is done once it left room in the output.
FlushCompress::Sync if input.is_empty() && !full => return Ok(()),
_ => {}
}
if taken == 0 && made == 0 && !full {
return Err(io::Error::other("the compressor made no progress"));
}
}
}
/// Return the number of uncompressed bytes supplied.
pub fn written(&self) -> u64 {
self.total
}
/// What is written next is compressed already (stored as it is), or not (compressed at the
/// default level).
pub fn packed(&mut self, packed: bool) -> io::Result<()> {
if packed == self.stored {
return Ok(());
}
self.deflate(&[], FlushCompress::Sync)?;
self.deflate = Compress::new(if packed { Compression::none() } else { Compression::default() }, false);
self.stored = packed;
Ok(())
}
/// Complete the gzip trailer and flush the underlying writer.
pub fn finish(mut self) -> io::Result<()> {
self.deflate(&[], FlushCompress::Finish)?;
self.out.write_all(&self.buf)?;
self.out.write_all(&self.crc.sum().to_le_bytes())?;
self.out.write_all(&self.crc.amount().to_le_bytes())?;
self.out.flush()
}
}
impl<W: Write> Write for Gz<W> {
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
self.write_all(buf)?;
Ok(buf.len())
}
fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
self.total = self.total.checked_add(buf.len() as u64).ok_or_else(|| io::Error::other("uncompressed byte count overflow"))?;
self.crc.update(buf);
self.deflate(buf, FlushCompress::None)
}
fn flush(&mut self) -> io::Result<()> {
// Flushing would end a deflate block: the stream is flushed when it is finished.
Ok(())
}
}
+77
View File
@@ -0,0 +1,77 @@
use std::io::{self, Read, Write};
use craft_gzip::Gz;
use flate2::{Compression, read::GzDecoder, write::GzEncoder};
fn decode(bytes: &[u8]) -> Vec<u8> {
let mut result = Vec::new();
GzDecoder::new(bytes).read_to_end(&mut result).unwrap();
result
}
#[test]
fn matches_flate2_without_mode_changes() {
let data = b"The quick brown fox jumps over the lazy dog. ".repeat(10000);
let mut expected = GzEncoder::new(Vec::new(), Compression::default());
let mut actual = Vec::new();
{
let mut gz = Gz::new(&mut actual).unwrap();
for chunk in data.chunks(131) {
expected.write_all(chunk).unwrap();
gz.write_all(chunk).unwrap();
}
assert_eq!(gz.written(), data.len() as u64);
gz.finish().unwrap();
}
assert_eq!(actual, expected.finish().unwrap());
assert_eq!(decode(&actual), data);
}
#[test]
fn mixed_segments_round_trip_and_stored_bytes_remain_uncompressed() {
let plain = b"repeat me ".repeat(20000);
let packed: Vec<u8> = (0..200_000).map(|i| (i * 31) as u8).collect();
let mut bytes = Vec::new();
{
let mut gz = Gz::new(&mut bytes).unwrap();
gz.write_all(&plain).unwrap();
gz.packed(true).unwrap();
gz.packed(true).unwrap();
gz.write_all(&packed).unwrap();
gz.packed(false).unwrap();
gz.write_all(&plain).unwrap();
assert_eq!(gz.written(), (plain.len() * 2 + packed.len()) as u64);
gz.finish().unwrap();
}
let expected = [plain.as_slice(), packed.as_slice(), plain.as_slice()].concat();
assert_eq!(decode(&bytes), expected);
assert!(bytes.windows(1024).any(|window| window == &packed[..1024]));
assert!(bytes.len() < expected.len());
}
struct FailAfter {
remaining: usize,
}
impl Write for FailAfter {
fn write(&mut self, data: &[u8]) -> io::Result<usize> {
if self.remaining == 0 {
return Err(io::Error::other("injected failure"));
}
let n = self.remaining.min(data.len());
self.remaining -= n;
Ok(n)
}
fn flush(&mut self) -> io::Result<()> {
Err(io::Error::other("injected flush failure"))
}
}
#[test]
fn propagates_header_body_and_flush_failures() {
assert!(Gz::new(FailAfter { remaining: 0 }).is_err());
let mut body = Gz::new(FailAfter { remaining: 10 }).unwrap();
body.packed(true).unwrap();
assert!(body.write_all(&vec![42; 200_000]).is_err());
let empty = Gz::new(FailAfter { remaining: usize::MAX }).unwrap();
assert_eq!(empty.finish().unwrap_err().to_string(), "injected flush failure");
}
+3 -3
View File
@@ -15,7 +15,7 @@
//! `IRMAK` and `ırmak`. Plain `str::to_lowercase` follows no locale and turns `İ` into `i` plus a
//! combining dot, which nothing typed would match.
//!
//! The Turkish i handling and sigma folding come from PdfCraft's `fold_case` (snipeTR,
//! The Turkish i handling and sigma folding come from `PdfCraft`'s `fold_case` (snipeTR,
//! nevicia2010-hub).
use std::ops::Range;
@@ -85,7 +85,7 @@ impl Folder {
}
/// One cluster, already in NFKD.
fn fold_cluster(&self, cluster: &str, out: &mut String) {
fn fold_cluster(self, cluster: &str, out: &mut String) {
let mut chars = cluster.chars().peekable();
while let Some(c) = chars.next() {
match c {
@@ -363,10 +363,10 @@ mod tests {
#[test]
fn matches_map_back_to_the_source() {
let f = Folder::new("en");
fn find<'a>(f: Folder, haystack: &'a str, needle: &str) -> Option<&'a str> {
f.fold(haystack).find(&f.fold(needle)).map(|r| &haystack[r])
}
let f = Folder::new("en");
let find = |haystack, needle| find(f, haystack, needle);
assert_eq!(find("Große Straße", "strasse"), Some("Straße"));
assert_eq!(find("Große Straße", "SS"), Some("ß"));
+5 -4
View File
@@ -4,7 +4,7 @@
use std::fmt;
use fixed_decimal::{Decimal, Sign};
use icu_decimal::{DecimalFormatter, parts};
use icu_decimal::{DecimalFormatter, options::DecimalFormatterOptions, parts};
use icu_locale_core::Locale;
use icu_locale_core::extensions::unicode::{key, value};
use writeable::{Part, PartsWrite, Writeable};
@@ -46,7 +46,8 @@ impl Format {
if digits == Digits::Latin {
locale.extensions.unicode.keywords.set(key!("nu"), value!("latn"));
}
let decimal = data::provider().and_then(|p| DecimalFormatter::try_new_with_buffer_provider(p, (&locale).into(), Default::default()).ok());
let decimal = data::provider()
.and_then(|p| DecimalFormatter::try_new_with_buffer_provider(p, (&locale).into(), DecimalFormatterOptions::default()).ok());
let mut format = Format { decimal, group: None, point: None, percent: ("", "%"), marks: Marks::default() };
// The locale's own separators and digits, read from a number that shows them all.
let probe = format.parts(&Decimal::try_from_str("-1234567.5").unwrap_or_default());
@@ -212,7 +213,7 @@ impl PartsWrite for Sink<'_> {
_ => return result,
};
if slot.is_empty() {
*slot = written.to_owned();
written.clone_into(slot);
}
}
result
@@ -370,7 +371,7 @@ mod tests {
for (tag, want) in
[("en", "50%"), ("de", "50\u{a0}%"), ("fr", "12,5\u{a0}%"), ("tr", "%50"), ("ar-EG", "٥٠٪\u{61c}"), ("fa", "۵۰٪"), ("hi", "50%")]
{
let decimals = if tag == "fr" { 1 } else { 0 };
let decimals = usize::from(tag == "fr");
let ratio = if tag == "fr" { 0.125 } else { 0.5 };
assert_eq!(Format::from_tag(tag).percent(ratio, decimals), want, "{tag}");
}
+6 -5
View File
@@ -113,7 +113,9 @@ impl Locale {
rows.entry(e.context).or_default().insert(e.source, e.translation);
}
}
problems.iter().for_each(|p| log::warn!("translation catalog: {p}; row skipped"));
for p in &problems {
log::warn!("translation catalog: {p}; row skipped");
}
Parsed { rows, problems }
})
}
@@ -483,14 +485,13 @@ fn wrap(initiator: char, value: &str) -> String {
PDF if open.last() == Some(&false) => {
open.pop();
}
PDF => continue,
PDI if isolates > 0 => {
while open.pop() == Some(false) {
out.push(PDF);
}
isolates -= 1;
}
PDI => continue,
PDF | PDI => continue,
_ => {}
}
out.push(c);
@@ -713,11 +714,11 @@ fn plural_rules(code: &str) -> Option<(PluralRules, Vec<PluralCategory>)> {
categories.push(c);
}
}
categories.sort_by_key(rank);
categories.sort_by_key(|c| rank(*c));
Some((rules, categories))
}
fn rank(c: &PluralCategory) -> u8 {
fn rank(c: PluralCategory) -> u8 {
match c {
PluralCategory::Zero => 0,
PluralCategory::One => 1,
+11
View File
@@ -80,6 +80,12 @@ impl Format {
///
/// Percent signs, units and the space before a unit (`50 %`, `12 px`) are not read; strip them
/// first. Anything else is an error rather than a guess.
///
/// # Errors
///
/// Returns `NumberError::Empty` for an empty input or one reduced to spaces and a sign,
/// `Unexpected` for an invalid character, `MixedDigits` for mixed digit sets, `Separator`
/// for misplaced marks, and `TooLarge` when the parsed value is not finite.
pub fn parse(&self, text: &str) -> Result<f64, NumberError> {
let marks = self.marks;
let text: String = text.chars().filter(|c| !is_bidi_mark(*c)).collect();
@@ -129,6 +135,11 @@ impl Format {
/// The number in `text` as `locale` (a language tag, `de-CH`, `ar_EG.UTF-8`) writes it:
/// [`Format::parse`] for [`Format::from_tag`]. Build the [`Format`] once to read many numbers. A
/// locale CLDR doesn't know reads as CLDR's root does (`1,234.5`).
///
/// # Errors
///
/// Returns the same `NumberError` as [`Format::parse`] for invalid digits, characters, or
/// separators, or when the value is not finite.
pub fn parse_number(text: &str, locale: &str) -> Result<f64, NumberError> {
Format::from_tag(locale).parse(text)
}
+1
View File
@@ -298,6 +298,7 @@ fn from_apple(identifier: &str, metric: bool, decimal: &str, grouping: &str, hou
/// A grouping separator the system sets: none at all when empty (Windows' `sThousand` the user
/// cleared), else one character.
#[cfg(any(test, windows, target_vendor = "apple"))]
#[expect(clippy::option_option, reason = "The public setting distinguishes following the locale, no grouping, and a custom separator")]
fn grouping(s: &str) -> Option<Option<char>> {
if s.is_empty() { Some(None) } else { single_char(s).map(Some) }
}
+17 -5
View File
@@ -113,7 +113,10 @@ pub enum Han {
/// Latin.
// ponytail: the languages a Craft app ships or could plausibly ship; add a row with the locale.
pub fn scripts(tag: &str) -> &'static [Script] {
use Script::*;
use Script::{
Arab, Armn, Beng, Cyrl, Deva, Ethi, Geor, Grek, Gujr, Guru, Hang, Hani, Hebr, Hira, Kana, Khmr, Knda, Laoo, Latn, Mlym, Mymr, Orya, Sinh,
Syrc, Taml, Telu, Thaa, Thai, Tibt,
};
let tag = Subtags::parse(tag);
if let Some(s) = tag.script.as_deref().and_then(subtag_scripts) {
return s;
@@ -175,7 +178,7 @@ pub fn base_direction(text: &str) -> Option<Direction> {
/// The forms a language tag's Han characters take: `zh-CN`, `zh-SG`, `zh-Hans` and plain `zh` →
/// Simplified; `zh-TW`, `zh-Hant` and the other regions CLDR writes in Traditional characters
/// (`zh-US`, `zh-AU`) → Traditional; `zh-HK`, `zh-MO`, `zh-Hant-HK` and `yue` → HongKong; `ja` →
/// (`zh-US`, `zh-AU`) → Traditional; `zh-HK`, `zh-MO`, `zh-Hant-HK` and `yue` → `HongKong`; `ja` →
/// Japanese; `ko` → Korean. `None` for a language not written with Han, which leaves the choice
/// to the font stack.
pub fn han(tag: &str) -> Option<Han> {
@@ -202,8 +205,14 @@ pub fn han(tag: &str) -> Option<Han> {
// ponytail: mn-CN → Mong is left out until vertical Mongolian layout is supported.
pub(crate) fn region_script(language: &str, region: &str) -> Option<&'static str> {
Some(match (language, region) {
("az", "iq" | "ir") | ("ha", "cm" | "sd") | ("kk", "af" | "cn" | "ir" | "mn") | ("ku", "iq" | "ir" | "lb") => "arab",
("ky", "cn") | ("ms", "cc") | ("pa", "pk") | ("tg", "pk") | ("uz", "af") => "arab",
("az", "iq" | "ir")
| ("ha", "cm" | "sd")
| ("kk", "af" | "cn" | "ir" | "mn")
| ("ku", "iq" | "ir" | "lb")
| ("ky", "cn")
| ("ms", "cc")
| ("pa" | "tg", "pk")
| ("uz", "af") => "arab",
("az", "ru") | ("ku", "am" | "az" | "ge" | "tm") | ("ug", "kz" | "mn") | ("uz", "cn") => "cyrl",
("ky", "tr") | ("sr", "me" | "ro" | "tr") => "latn",
("sd", "in") => "deva",
@@ -216,7 +225,10 @@ pub(crate) fn region_script(language: &str, region: &str) -> Option<&'static str
/// The scripts a script subtag stands for, including the CLDR unions (`jpan`, `kore`). `None` for
/// one not in [`Script`], so the language's own scripts apply.
fn subtag_scripts(subtag: &str) -> Option<&'static [Script]> {
use Script::*;
use Script::{
Arab, Armn, Beng, Cyrl, Deva, Ethi, Geor, Grek, Gujr, Guru, Hang, Hani, Hebr, Hira, Kana, Khmr, Knda, Laoo, Latn, Mlym, Mong, Mymr, Orya,
Sinh, Syrc, Taml, Telu, Thaa, Thai, Tibt,
};
Some(match subtag {
"hans" | "hant" | "hani" => &[Hani],
"jpan" => &[Hani, Hira, Kana],
+5
View File
@@ -104,6 +104,10 @@ impl FileSize {
}
/// The unit `bytes` is written in, the number in it and its digits after the point.
#[expect(
clippy::cast_precision_loss,
reason = "File sizes are displayed as rounded f64 values; exact u64 arithmetic is not required for presentation"
)]
fn parts(&self, bytes: u64) -> (SizeUnit, f64, usize) {
let (smallest, largest) = (self.smallest.min(self.largest), self.largest);
let mut unit = smallest;
@@ -137,6 +141,7 @@ impl FileSize {
}
}
#[expect(clippy::cast_precision_loss, reason = "Unit scales are displayed as f64 values; exact u64 arithmetic is not required for presentation")]
fn scale(&self, unit: SizeUnit) -> f64 {
(self.step as f64).powi(unit as i32)
}
+1
View File
@@ -51,6 +51,7 @@ exr = { version = "1.73", default-features = false, features = ["rayon"] }
proptest = { workspace = true }
image = { version = "0.25", default-features = false, features = ["png", "jpeg", "tiff"] }
sha2 = { version = "0.10", default-features = false, features = ["std"] }
craft-media-testkit = { workspace = true }
[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]
craft-video = { workspace = true, features = ["av1-decode"] }
+123
View File
@@ -0,0 +1,123 @@
JPEG encoding dependency: jpeg-encoder 0.6.1
Source: https://crates.io/crates/jpeg-encoder/0.6.1
Declared license: (MIT OR Apache-2.0) AND IJG.
This software is based in part on the work of the Independent JPEG Group.
The MIT license and unaltered upstream IJG and SIMD notices follow. The Apache-2.0
alternative is also retained in licenses/jpeg-encoder-0.6.1 at the repository root
(https://github.com/storytold/craft-libs/tree/main/licenses/jpeg-encoder-0.6.1).
The dependency is used unmodified; no encoder implementation is vendored here.
LICENSE-MIT
Copyright (c) 2021 Volker Ströbel <volkerstroebel@mysurdity.de>
Permission is hereby granted, free of charge, to any
person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the
Software without restriction, including without
limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software
is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice
shall be included in all copies or substantial portions
of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
Original src/fdct.rs opening notice
/*
* Ported from mozjpeg to rust
*
* This file was part of the Independent JPEG Group's software:
* Copyright (C) 1991-1996, Thomas G. Lane.
* libjpeg-turbo Modifications:
* Copyright (C) 2015, 2020, D. R. Commander.
*
* Conditions of distribution and use:
* In plain English:
*
* 1. We don't promise that this software works. (But if you find any bugs,
* please let us know!)
* 2. You can use this software for whatever you want. You don't have to pay us.
* 3. You may not pretend that you wrote this software. If you use it in a
* program, you must acknowledge somewhere in your documentation that
* you've used the IJG code.
*
* In legalese:
*
* The authors make NO WARRANTY or representation, either express or implied,
* with respect to this software, its quality, accuracy, merchantability, or
* fitness for a particular purpose. This software is provided "AS IS", and you,
* its user, assume the entire risk as to its quality and accuracy.
*
* This software is copyright (C) 1991-2020, Thomas G. Lane, Guido Vollbeding.
* All Rights Reserved except as specified below.
*
* Permission is hereby granted to use, copy, modify, and distribute this
* software (or portions thereof) for any purpose, without fee, subject to these
* conditions:
* (1) If any part of the source code for this software is distributed, then this
* README file must be included, with this copyright and no-warranty notice
* unaltered; and any additions, deletions, or changes to the original files
* must be clearly indicated in accompanying documentation.
* (2) If only executable code is distributed, then the accompanying
* documentation must state that "this software is based in part on the work of
* the Independent JPEG Group".
* (3) Permission for use of this software is granted only if the user accepts
* full responsibility for any undesirable consequences; the authors accept
* NO LIABILITY for damages of any kind.
*
* These conditions apply to any software derived from or based on the IJG code,
* not just to the unmodified library. If you use our work, you ought to
* acknowledge us.
*
* Permission is NOT granted for the use of any IJG author's name or company name
* in advertising or publicity relating to this software or products derived from
* it. This software may be referred to only as "the Independent JPEG Group's
* software".
*
* We specifically permit and encourage the use of this software as the basis of
* commercial products, provided that all warranty or liability claims are
* assumed by the product vendor.
*
* This file contains a slower but more accurate integer implementation of the
* forward DCT (Discrete Cosine Transform).
*
* A 2-D DCT can be done by 1-D DCT on each row followed by 1-D DCT
* on each column. Direct algorithms are also available, but they are
* much more complex and seem not to be any faster when reduced to code.
*
* This implementation is based on an algorithm described in
* C. Loeffler, A. Ligtenberg and G. Moschytz, "Practical Fast 1-D DCT
* Algorithms with 11 Multiplications", Proc. Int'l. Conf. on Acoustics,
* Speech, and Signal Processing 1989 (ICASSP '89), pp. 988-991.
* The primary algorithm described there uses 11 multiplies and 29 adds.
* We use their alternate method with 12 multiplies and 32 adds.
* The advantage of this method is that no data path contains more than one
* multiplication; this allows a very simple and accurate implementation in
* scaled fixed-point arithmetic, with a minimal number of shifts.
*/
Original src/avx2/fdct.rs opening notice
/*
* Ported from mozjpeg / jfdctint-avx2.asm to rust
* Copyright 2009 Pierre Ossman <ossman@cendio.se> for Cendio AB
* Copyright (C) 2009, 2016, 2018, 2020, D. R. Commander.
*
* Based on the x86 SIMD extension for IJG JPEG library
* Copyright (C) 1999-2006, MIYASAKA Masaru.
*/
+10
View File
@@ -57,6 +57,7 @@ craft-image-codecs = { git = "https://github.com/storytold/craft-libs", rev = "<
| Cineon | yes | yes | U16 (10-bit code values read and written exactly through U16) | Gray, RGB | no | no | no | no | no | no | no | built in |
| DICOM | yes | **no** | U8, U16 | Gray, RGB | no | no | no | no | no | no | n/a | built in |
| Amiga IFF (ILBM/PBM) | yes | yes (24-bit ILBM) | U8 | RGB, RGBA | yes (1-bit mask plane on write) | no | no | no | no | no | no | built in |
| JPEG-LS (`.jls`) | yes (any NEAR; one scan per component) | yes (lossless) | U8, U16 | Gray, RGB | no | no | no | no | no | no | no | built in |
| AVIF | with feature `avif-decode` (native only) | only with feature `avif` | U8, U16 (10/12-bit decodes to U16; PQ/HLG to linear F32) | RGB, RGBA | yes (auxiliary alpha) | read (`colr` prof/rICC) | read | read | no | no | yes | `craft-video` AV1 decoder; `image` + `ravif` to write |
| HEIF/HEIC | with feature `heif` | **no** | U8, U16 (10/12-bit decodes to U16) | RGB, RGBA | yes (auxiliary alpha) | yes (`colr` prof) | yes | yes | no | no | n/a | `heic-rs` |
@@ -350,3 +351,12 @@ folder, copy the five files from that commit into `corpus/exr/`, or run
at commit `74330157cb601573ae4523a95bb9132822fc3918` and copy its `corpus/exr/` here, as CI does.
The images are not committed here; OpenEXR distributes them under its
[license](https://github.com/AcademySoftwareFoundation/openexr/blob/69b2604fc76e370615438bdc8d2cd95b9349c12e/LICENSE.md).
## Redistribution notices
JPEG encoding uses `jpeg-encoder` 0.6.1, including work from the Independent JPEG Group.
Retain this crate's [NOTICE](NOTICE) with binary distributions using that encoder. It includes
its MIT license, the IJG acknowledgement and original IJG/SIMD notices. Both upstream license
alternatives and source checksums are retained in
[`licenses/jpeg-encoder-0.6.1`](https://github.com/storytold/craft-libs/tree/main/licenses/jpeg-encoder-0.6.1)
at the repository root.
+145
View File
@@ -0,0 +1,145 @@
//! Header-only BMP dimensions and pixel-data coverage, without allocating a canvas.
/// Coverage of the declared pixel array. Row byte counts include row padding; RLE coverage
/// counts the pixels drawn by commands and may be smaller than the canvas.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Coverage {
pub pixels: u64,
pub row_bytes: Option<(u64, u64)>,
}
/// Inspect pixel data for the given dimensions without decoding a bitmap. The row tuple is
/// `(available, needed)`; callers choose their own sparse-canvas and allocation policy.
pub fn coverage(bytes: &[u8], w: u32, h: u32) -> Coverage {
match bmp_layout(bytes) {
BmpLayout::Rle { offset, rle4 } => Coverage { pixels: bmp_rle_pixels(bytes, offset, rle4, w, h), row_bytes: None },
BmpLayout::Rows { offset, bits } => {
let needed = u64::from(w).saturating_mul(u64::from(bits)).div_ceil(32).saturating_mul(4).saturating_mul(u64::from(h));
let held = bytes.len().saturating_sub(offset) as u64;
Coverage { pixels: u64::from(w) * u64::from(h), row_bytes: Some((held, needed)) }
}
}
}
enum BmpLayout {
/// RLE8 or RLE4 commands.
Rle { offset: usize, rle4: bool },
/// Rows of `bits` per pixel, each padded to 4 bytes.
Rows { offset: usize, bits: u16 },
}
/// The layout the decoder reads, from the file header and the bitmap header: a 12-byte core header
/// (bits per pixel at 24, never compressed) or a 40-byte or larger one (bits at 28, compression at
/// 30). Fields the decoder would have refused are read as 1 bit per pixel at offset 0, the most
/// lenient layout.
fn bmp_layout(bytes: &[u8]) -> BmpLayout {
let u16_at = |i: usize| bytes.get(i..i.checked_add(2)?).and_then(|b| b.try_into().ok()).map(u16::from_le_bytes);
let u32_at = |i: usize| bytes.get(i..i.checked_add(4)?).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes);
let offset = u32_at(10).and_then(|o| usize::try_from(o).ok()).unwrap_or(0);
let (bits, compression) = match u32_at(14) {
Some(12) => (u16_at(24), Some(0)),
_ => (u16_at(28), u32_at(30)),
};
match compression {
Some(1) => BmpLayout::Rle { offset, rle4: false },
Some(2) => BmpLayout::Rle { offset, rle4: true },
_ => BmpLayout::Rows { offset, bits: bits.filter(|&b| b > 0).unwrap_or(1) },
}
}
/// The pixels an RLE8 or RLE4 BMP's commands draw on a `w` × `h` canvas, read the way the decoder
/// paints them: a run is clipped at the end of its row, an end-of-row code moves to the next row, a
/// delta skips pixels (left blank), and an end-of-bitmap code, a truncated command or the last row
/// ends the picture. Every command takes at least 2 bytes, so the walk is linear in the file.
fn bmp_rle_pixels(bytes: &[u8], offset: usize, rle4: bool, w: u32, h: u32) -> u64 {
let (w, h) = (u64::from(w), u64::from(h));
let (mut pos, mut x, mut y, mut covered) = (offset, 0u64, 0u64, 0u64);
while y < h {
let (Some(&count), Some(&value)) = (bytes.get(pos), bytes.get(pos.saturating_add(1))) else {
break;
};
pos = pos.saturating_add(2);
match (count, value) {
// end of row
(0, 0) => (x, y) = (0, y.saturating_add(1)),
// end of bitmap
(0, 1) => break,
// delta: right and down
(0, 2) => {
let (Some(&dx), Some(&dy)) = (bytes.get(pos), bytes.get(pos.saturating_add(1))) else {
break;
};
pos = pos.saturating_add(2);
(x, y) = (x.saturating_add(u64::from(dx)), y.saturating_add(u64::from(dy)));
}
// absolute: `value` pixels stored one per byte (RLE8) or nibble (RLE4), padded to 2 bytes
(0, n) => {
let len = if rle4 { usize::from(n).div_ceil(2) } else { usize::from(n) };
pos = pos.saturating_add(len + (len & 1));
if pos > bytes.len() {
break;
}
covered = covered.saturating_add(u64::from(n).min(w.saturating_sub(x)));
x = x.saturating_add(u64::from(n));
}
// a run of `count` pixels
(n, _) => {
covered = covered.saturating_add(u64::from(n).min(w.saturating_sub(x)));
x = x.saturating_add(u64::from(n));
}
}
}
covered
}
/// Reads BMP `(width, height)` from the DIB header without allocating.
pub fn dimensions(bytes: &[u8]) -> Option<(u32, u32)> {
if bytes.get(0..2) != Some(b"BM") {
return None;
}
let dib = u32::from_le_bytes(bytes.get(14..18)?.try_into().ok()?);
let (w, h) = if dib == 12 {
(u16::from_le_bytes(bytes.get(18..20)?.try_into().ok()?) as u32, u16::from_le_bytes(bytes.get(20..22)?.try_into().ok()?) as u32)
} else {
let w = i32::from_le_bytes(bytes.get(18..22)?.try_into().ok()?);
let h = i32::from_le_bytes(bytes.get(22..26)?.try_into().ok()?);
(u32::try_from(w).ok()?, h.unsigned_abs())
};
Some((w, h))
}
#[cfg(test)]
mod tests {
use super::*;
fn bmp(compression: u32, pixels: &[u8]) -> Vec<u8> {
let mut b = vec![0; 54];
b[..2].copy_from_slice(b"BM");
b[10..14].copy_from_slice(&54u32.to_le_bytes());
b[14..18].copy_from_slice(&40u32.to_le_bytes());
b[18..22].copy_from_slice(&4i32.to_le_bytes());
b[22..26].copy_from_slice(&2i32.to_le_bytes());
b[28..30].copy_from_slice(&8u16.to_le_bytes());
b[30..34].copy_from_slice(&compression.to_le_bytes());
b.extend_from_slice(pixels);
b
}
#[test]
fn dimensions_and_padded_rows() {
let b = bmp(0, &[0; 7]);
assert_eq!(dimensions(&b), Some((4, 2)));
assert_eq!(coverage(&b, 4, 2), Coverage { pixels: 8, row_bytes: Some((7, 8)) });
assert_eq!(dimensions(&b[..20]), None);
}
#[test]
fn rle_counts_clipped_runs_deltas_and_complete_absolute_blocks() {
let b = bmp(1, &[3, 7, 0, 0, 0, 2, 1, 0, 0, 3, 1, 2, 3, 0, 0, 1]);
assert_eq!(coverage(&b, 4, 2).pixels, 6);
let truncated = bmp(1, &[0, 4, 1, 2]);
assert_eq!(coverage(&truncated, 4, 2).pixels, 0);
let nibble = bmp(2, &[0, 3, 0x12, 0x30, 0, 1]);
assert_eq!(coverage(&nibble, 4, 2).pixels, 3);
}
}
+1
View File
@@ -15,6 +15,7 @@ pub(crate) mod heif;
pub(crate) mod iff;
pub(crate) mod jp2;
pub(crate) mod jpeg;
pub(crate) mod jpegls;
pub(crate) mod jxl;
pub(crate) mod pcx;
pub(crate) mod png;
+124 -13
View File
@@ -18,7 +18,8 @@
//! Bounded for hostile input: box nesting, item, property and extent counts are capped; item data
//! can't add up to more than the file; the [`Limits`] are checked against the declared size
//! before any picture is decoded, against every decoded picture and against each output buffer;
//! the AV1 decoder's picture store is capped by `max_alloc` too; and a panic in the decoder is
//! the AV1 decoder's picture store and the pictures one chunk may show are capped by `max_alloc`
//! too; repeated transforms are refused; and a panic in the decoder is
//! a malformed-file error. wasm32 builds leave AVIF unreadable: a panic there aborts instead of
//! unwinding.
//!
@@ -150,7 +151,7 @@ struct Loc {
extents: Vec<Extent>,
}
#[derive(Clone, Copy, Debug)]
#[derive(Clone, Copy, Debug, PartialEq)]
enum Transform {
/// Clean aperture: width, height, horizontal and vertical offset of the centre.
Clap { w: f64, h: f64, dx: f64, dy: f64 },
@@ -371,15 +372,18 @@ fn parse_prop(t: &[u8; 4], b: &[u8]) -> Result<Prop> {
b"irot" => Prop::T(Transform::Rot(r.u8()? & 3)),
b"imir" => Prop::T(Transform::Mir(r.u8()? & 1)),
b"clap" => {
let mut q = || -> Result<f64> {
let n = r.u32()? as i32;
let d = r.u32()? as i32;
// Width and height are unsigned fractions; the centre offsets have signed numerators
// (and unsigned denominators), as libavif and libheif read them.
let mut q = |signed: bool| -> Result<f64> {
let raw = r.u32()?;
let n = if signed { f64::from(raw as i32) } else { f64::from(raw) };
let d = r.u32()?;
if d == 0 {
return Err(bad("clap with a zero denominator"));
}
Ok(f64::from(n) / f64::from(d))
Ok(n / f64::from(d))
};
let (w, h, dx, dy) = (q()?, q()?, q()?, q()?);
let (w, h, dx, dy) = (q(false)?, q(false)?, q(true)?, q(true)?);
Prop::T(Transform::Clap { w, h, dx, dy })
}
_ => Prop::Other,
@@ -429,8 +433,19 @@ impl Container<'_> {
fn ispe(&self, id: u32) -> Option<(u32, u32)> {
self.props_of(id).find_map(|p| if let Prop::Ispe(w, h) = p { Some((*w, *h)) } else { None })
}
fn transforms(&self, id: u32) -> Vec<Transform> {
self.props_of(id).filter_map(|p| if let Prop::T(t) = p { Some(*t) } else { None }).collect()
/// The item's transformative properties in association order. HEIF allows each of `clap`,
/// `irot` and `imir` at most once per item; a file that associates one more often (repeated
/// `ipma` entries could otherwise ask for a quarter of a million full-image rotations) is
/// refused before any pixels are touched.
fn transforms(&self, id: u32) -> Result<Vec<Transform>> {
// Three is the most a valid item has, so a fourth is already a repeat.
let ts: Vec<Transform> = self.props_of(id).filter_map(|p| if let Prop::T(t) = p { Some(*t) } else { None }).take(4).collect();
for (i, t) in ts.iter().enumerate() {
if ts[..i].iter().any(|u| std::mem::discriminant(u) == std::mem::discriminant(t)) {
return Err(bad("an image item has a transformative property (clap, irot or imir) more than once"));
}
}
Ok(ts)
}
fn nclx(&self, id: u32) -> Option<Cicp> {
self.props_of(id).find_map(|p| if let Prop::Nclx(n) = p { Some(*n) } else { None })
@@ -504,7 +519,7 @@ pub(crate) fn probe(bytes: &[u8], limits: &Limits) -> Result<(u32, u32)> {
let c = parse(bytes)?;
let (w, h) = item_size(&c, c.primary)?;
limits.check_size(w, h)?;
Ok(displayed(w, h, &c.transforms(c.primary)))
Ok(displayed(w, h, &c.transforms(c.primary)?))
}
/// One decoded AV1 picture.
@@ -539,6 +554,9 @@ fn decode_av1(c: &Container, id: u32, limits: &Limits) -> Result<Pic> {
let config = c.props_of(id).find_map(|p| if let Prop::Av1c(o) = p { Some(o.clone()) } else { None });
let mut dec = av1::Decoder::new();
dec.set_memory_budget(limits.max_alloc.min(AV1_MEMORY_BUDGET));
// Only the first picture is kept, so the pictures a chunk may show are held to the same budget
// before they are built (the decoder allows up to 1 GiB of them otherwise).
dec.set_shown_budget(limits.max_alloc);
let mut pics = catch_unwind(AssertUnwindSafe(|| -> std::result::Result<Vec<av1::Picture>, av1::Error> {
let mut pics = Vec::new();
// The sequence header normally travels in the item too; the av1C copy covers files
@@ -580,7 +598,9 @@ fn coefficients(matrix: u16, primaries: u16) -> Result<Option<(f32, f32)>> {
1 => Some((0.2126, 0.0722)),
4 => Some((0.30, 0.11)),
7 => Some((0.212, 0.087)),
9 | 10 => Some((0.2627, 0.0593)),
// 9 is BT.2020 non-constant luminance; 10 (constant luminance) needs other equations and
// is refused below.
9 => Some((0.2627, 0.0593)),
// Chromaticity-derived non-constant luminance.
12 => {
let [kr, _, kb] = crate::cicp::luma_weights(primaries);
@@ -830,6 +850,16 @@ pub(crate) fn decode_with_depth(bytes: &[u8], limits: &Limits, keep_orientation:
let id = c.primary;
let (w, h) = item_size(&c, id)?;
let alpha = c.alpha_item().filter(|&a| item_size(&c, a).is_ok_and(|s| s == (w, h)));
let transforms = c.transforms(id)?;
// The alpha plane is composed in stored orientation and turned with the colour, which is right
// when it has no transforms of its own (what encoders write) or the colour's. Others would put
// transparency in the wrong place, so they are refused rather than ignored.
if let Some(a) = alpha {
let own = c.transforms(a)?;
if !own.is_empty() && own != transforms {
return Err(CodecError::unsupported(F, "an alpha plane with transforms (clap, irot, imir) that differ from the image's"));
}
}
let layout = if alpha.is_some() { ChannelLayout::Rgba } else { ChannelLayout::Rgb };
// The declared size, before any picture is decoded.
let mut canvas = Canvas::new(w, h, layout, limits)?;
@@ -846,7 +876,7 @@ pub(crate) fn decode_with_depth(bytes: &[u8], limits: &Limits, keep_orientation:
}
}
if !keep_orientation {
canvas = apply_transforms(canvas, &c.transforms(id));
canvas = apply_transforms(canvas, &transforms);
}
let (w, h) = (canvas.w as u32, canvas.h as u32);
let image = Image::from_u16(w, h, layout, &canvas.data)?;
@@ -1075,6 +1105,87 @@ mod tests {
assert_eq!((kept.width(), kept.height(), rgb8(&kept)), (33, 17, QUAD_SOURCE.to_vec()));
}
/// A `clap` box: width, height, horizontal and vertical offset, each numerator then denominator.
fn clap_box(f: [u32; 8]) -> Vec<u8> {
bx(b"clap", &f.iter().flat_map(|v| v.to_be_bytes()).collect::<Vec<_>>())
}
#[test]
fn clean_aperture_sizes_are_unsigned() {
let (av1, cfg) = av1_of(QUAD_GBR_LOSSLESS);
let av1c = bx(b"av1C", &[&[0x81, 0, 0, 0][..], &cfg].concat());
// A 2 × 2 aperture with its width written as 0x80000000 / 0x40000000, centred one pixel
// left of the image centre (a signed offset numerator: -1 / 1).
let clap = clap_box([0x8000_0000, 0x4000_0000, 2, 1, (-1i32) as u32, 1, 0, 1]);
let file = build(&[(1, b"av01", &av1, &[1, 2, 3])], &[ispe(33, 17), av1c, clap], &[]);
assert_eq!(crate::probe_size(&file).unwrap(), (2, 2));
let img = crate::decode(&file).unwrap();
assert_eq!((img.width(), img.height()), (2, 2));
// Centre (16, 8) moved to (15, 8): the 2 × 2 crop starts at (15, 8) (rounded from 14.5, 7.5).
let got = rgb8(&img);
let (x0, y0) = ((32.0f64 / 2.0 - 1.0 - 0.5).round() as usize, (16.0f64 / 2.0 - 0.5).round() as usize);
for y in 0..2 {
for x in 0..2 {
let s = ((y0 + y) * 33 + x0 + x) * 3;
assert_eq!(&got[(y * 2 + x) * 3..][..3], &QUAD_SOURCE[s..s + 3], "({x}, {y})");
}
}
}
#[test]
fn repeated_transforms_are_refused() {
let (av1, cfg) = av1_of(QUAD_GBR_LOSSLESS);
let av1c = bx(b"av1C", &[&[0x81, 0, 0, 0][..], &cfg].concat());
// the same irot associated twice, and through two ipma entries for the item
let twice = build(&[(1, b"av01", &av1, &[1, 2, 3, 3])], &[ispe(33, 17), av1c.clone(), bx(b"irot", &[1])], &[]);
assert!(matches!(crate::probe_size(&twice), Err(CodecError::Malformed { .. })));
assert!(matches!(crate::decode(&twice), Err(CodecError::Malformed { .. })));
let mut many = build(&[(1, b"av01", &av1, &[1, 2, 3])], &[ispe(33, 17), av1c.clone(), bx(b"irot", &[1])], &[]);
let c = parse(&many).unwrap();
assert_eq!(c.transforms(1).unwrap(), vec![Transform::Rot(1)]);
// 1024 more ipma records for item 1, each repeating the irot 255 times
let mut ipma = vec![0, 0, 0, 0];
ipma.extend_from_slice(&1024u32.to_be_bytes());
for _ in 0..1024 {
ipma.extend_from_slice(&[0, 1, 255]);
ipma.extend(std::iter::repeat_n(3u8, 255));
}
many = build(&[(1, b"av01", &av1, &[1, 2])], &[ispe(33, 17), av1c, bx(b"irot", &[1])], &[]);
let mut c = parse(&many).unwrap();
parse_ipma(&ipma, &mut c).unwrap();
assert!(matches!(c.transforms(1), Err(CodecError::Malformed { .. })));
// each kind once is fine, in any order
let ok = build(
&[(1, b"av01", &av1, &[1, 2, 3, 4, 5])],
&[
ispe(33, 17),
bx(b"av1C", &[&[0x81, 0, 0, 0][..], &cfg].concat()),
clap_box([33, 1, 17, 1, 0, 1, 0, 1]),
bx(b"irot", &[1]),
bx(b"imir", &[0]),
],
&[],
);
assert_eq!(crate::probe_size(&ok).unwrap(), (17, 33));
}
#[test]
fn alpha_with_transforms_of_its_own_is_refused() {
let (av1, cfg) = av1_of(QUAD_GBR_LOSSLESS);
let av1c = bx(b"av1C", &[&[0x81, 0, 0, 0][..], &cfg].concat());
let auxc = fbx(b"auxC", b"urn:mpeg:mpegB:cicp:systems:auxiliary:alpha\0");
let props = [ispe(33, 17), av1c, auxc, bx(b"imir", &[1])];
let with = |colour: &[u8], alpha: &[u8]| build(&[(1, b"av01", &av1, colour), (2, b"av01", &av1, alpha)], &props, &[(b"auxl", 2, &[1])]);
// no transforms on the alpha plane, or the colour's: composed, then turned together
let plain = crate::decode(&with(&[1, 2], &[1, 2, 3])).unwrap();
assert_eq!(plain.layout(), ChannelLayout::Rgba);
let both = crate::decode(&with(&[1, 2, 4], &[1, 2, 3, 4])).unwrap();
let alpha_free = crate::decode(&with(&[1, 2, 4], &[1, 2, 3])).unwrap();
assert_eq!(both.to_rgba8(), alpha_free.to_rgba8());
// an alpha-only mirror would put transparency on the wrong side
assert!(matches!(crate::decode(&with(&[1, 2], &[1, 2, 3, 4])), Err(CodecError::Unsupported { .. })));
}
#[test]
fn transforms_rotate_mirror_and_crop() {
// 3 × 2, one channel, value = index
@@ -1164,7 +1275,7 @@ mod tests {
#[test]
fn unsupported_matrices_are_errors() {
for m in [8u16, 11, 13, 14] {
for m in [8u16, 10, 11, 13, 14] {
assert!(matches!(coefficients(m, 1), Err(CodecError::Unsupported { .. })), "{m}");
}
assert_eq!(coefficients(0, 1).unwrap(), None);
+41 -2
View File
@@ -195,6 +195,27 @@ enum DataEnd {
/// measured on these, not on the file length, which APP padding can inflate without
/// adding image data.
fn data_end(b: &[u8]) -> (DataEnd, u64) {
data_end_mode(b, false)
}
/// Whether the marker walk actually reaches the first EOI, with malformed segment lengths refused.
pub(crate) fn reaches_eoi(b: &[u8]) -> bool {
data_end_mode(b, true).0 == DataEnd::Complete
}
fn find_ff(b: &[u8]) -> Option<usize> {
const ONES: u64 = 0x0101_0101_0101_0101;
let (words, tail) = b.as_chunks::<8>();
for (i, word) in words.iter().enumerate() {
let x = !u64::from_ne_bytes(*word);
if x.wrapping_sub(ONES) & !x & (ONES << 7) != 0 {
return word.iter().position(|&v| v == 0xff).map(|j| i * 8 + j);
}
}
tail.iter().position(|&v| v == 0xff).map(|j| words.len() * 8 + j)
}
fn data_end_mode(b: &[u8], strict: bool) -> (DataEnd, u64) {
// Where the bytes run out: inside the image data once a scan has held some.
let cut = |scan_data: bool, scanned: u64| (if scan_data { DataEnd::Truncated } else { DataEnd::Empty }, scanned);
let mut i = 2; // past SOI
@@ -207,7 +228,7 @@ fn data_end(b: &[u8]) -> (DataEnd, u64) {
// segments after the stray bytes (padding among them) are still recognised. Stray
// bytes are not scan data, so they never count (junk would buy budget as padding
// did); with no marker left, the image data ends here.
let Some(p) = b.get(i..).and_then(|r| r.iter().position(|&v| v == 0xFF)) else { return cut(scan_data, scanned) };
let Some(p) = b.get(i..).and_then(find_ff) else { return cut(scan_data, scanned) };
i += p;
continue;
}
@@ -216,15 +237,19 @@ fn data_end(b: &[u8]) -> (DataEnd, u64) {
0xD9 => return (DataEnd::Complete, scanned),
0xFF => i += 1,
0x01 | 0xD0..=0xD8 => i += 2,
0x00 if strict => i += 2,
_ => {
let Some(len) = b.get(i + 2..i + 4).and_then(|s| <[u8; 2]>::try_from(s).ok()).map(u16::from_be_bytes) else {
return cut(scan_data, scanned);
};
if strict && len < 2 {
return cut(scan_data, scanned);
}
i = i.saturating_add(2 + usize::from(len));
if code == 0xDA {
let start = i;
loop {
let Some(p) = b.get(i..).and_then(|r| r.iter().position(|&v| v == 0xFF)) else {
let Some(p) = b.get(i..).and_then(find_ff) else {
// EOF inside this scan: everything from the scan start to the end
// of the file is scan data (inside a declared segment it may not
// be, so only count what remains).
@@ -653,6 +678,20 @@ mod tests {
}
/// `info` reads the frame from the markers, and which decoder the file goes to.
#[test]
fn ff_search_matches_plain_search() {
let mut b: Vec<u8> = (0..300u32).map(|i| (i * 7 % 255) as u8).collect();
for at in [None, Some(0), Some(7), Some(8), Some(15), Some(203), Some(296), Some(299)] {
if let Some(i) = at {
b[i] = 0xff;
}
for start in [0, 1, 5, 9, 290, 299, 300] {
let s = &b[start..];
assert_eq!(find_ff(s), s.iter().position(|&v| v == 0xff));
}
}
}
#[test]
fn info_reads_the_frame_and_the_decoder() {
let img = Image::from_raw(37, 21, ChannelLayout::Rgb, SampleType::U8, vec![128; 37 * 21 * 3]).unwrap();
+870
View File
@@ -0,0 +1,870 @@
//! JPEG-LS (ITU-T T.87 | ISO/IEC 14495-1, "LOCO-I"): lossless and near-lossless gray and RGB
//! images, 2 to 16 bits per sample.
//!
//! Read: baseline JPEG-LS with the default or `LSE`-preset coding parameters, any `NEAR`, and
//! scans that code one component each (`ILV` 0), which is also how this module writes. Line- and
//! sample-interleaved scans, colour transforms and mapping tables are reported as unsupported.
//! Write: lossless (`NEAR` 0), 8 or 16 bits, gray or RGB, one scan per component.
//!
//! Samples of 9 to 15 bits are scaled to 16 bits on read (the top bits are repeated into the low
//! ones), so a decoded image always spans the full range of its sample type.
use crate::error::CodecError;
use crate::fidelity::Plan;
use crate::format::Format;
use crate::image::{ChannelLayout, Image, SampleType};
use crate::options::Limits;
const F: Format = Format::JpegLs;
const SOF55: u8 = 0xF7;
const LSE: u8 = 0xF8;
const RESET_DEFAULT: i32 = 64;
const MIN_C: i32 = -128;
const MAX_C: i32 = 127;
/// `J[RUNindex]`: the log2 of the run length a run-index step codes.
const J: [u32; 32] = [0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 9, 10, 11, 12, 13, 14, 15];
/// Context slots: the regular contexts (365 of the 405 slots the index below can reach), then the two
/// run-interruption contexts.
const RI_BASE: usize = 405;
const CONTEXTS: usize = RI_BASE + 2;
fn bad(reason: impl std::fmt::Display) -> CodecError {
CodecError::malformed(F, reason)
}
/// Whether `b` is a JPEG-LS file: an SOI followed by marker segments up to an SOF55 frame header.
pub(crate) fn looks_like_jpegls(b: &[u8]) -> bool {
if !b.starts_with(&[0xFF, 0xD8]) {
return false;
}
let mut pos = 2;
for _ in 0..64 {
let (Some(&0xFF), Some(&marker)) = (b.get(pos), b.get(pos + 1)) else { return false };
match marker {
SOF55 => return true,
0xDA | 0xD9 => return false,
0xC0..=0xCF | 0xDB..=0xDF => return false,
0x01 | 0xD0..=0xD7 | 0xFF => pos += if marker == 0xFF { 1 } else { 2 },
_ => {
let Some(len) = b.get(pos + 2..pos + 4).map(|l| usize::from(u16::from_be_bytes([l[0], l[1]]))) else { return false };
pos += 2 + len;
}
}
}
false
}
/// The coding parameters of one scan, derived as T.87 section C.2 specifies.
#[derive(Clone, Copy)]
struct Params {
maxval: i32,
near: i32,
range: i32,
qbpp: u32,
limit: u32,
t1: i32,
t2: i32,
t3: i32,
reset: i32,
}
fn ceil_log2(v: i32) -> u32 {
let mut n = 0;
while (1i64 << n) < i64::from(v) {
n += 1;
}
n
}
impl Params {
/// `preset` holds the `LSE` values (`maxval`, `t1`, `t2`, `t3`, `reset`), 0 where absent.
fn new(precision: u32, near: i32, preset: [i32; 5]) -> Result<Params, CodecError> {
let default_max = (1i32 << precision) - 1;
let maxval = if preset[0] == 0 { default_max } else { preset[0] };
if maxval < 1 || maxval > default_max || near < 0 || near > (maxval / 2).min(255) {
return Err(bad("invalid MAXVAL or NEAR"));
}
let clamp = |v: i32, lo: i32, hi: i32| if v > hi || v < lo { lo } else { v };
let (d1, d2, d3) = if maxval >= 128 {
let factor = (maxval.min(4095) + 128) / 256;
let t1 = clamp(factor + 2 + 3 * near, near + 1, maxval);
let t2 = clamp(factor * 4 + 3 + 5 * near, t1, maxval);
let t3 = clamp(factor * 17 + 4 + 7 * near, t2, maxval);
(t1, t2, t3)
} else {
let factor = 256 / (maxval + 1);
let t1 = clamp((3 / factor + 3 * near).max(2), near + 1, maxval);
let t2 = clamp((7 / factor + 5 * near).max(3), t1, maxval);
let t3 = clamp((21 / factor + 7 * near).max(4), t2, maxval);
(t1, t2, t3)
};
let t1 = if preset[1] == 0 { d1 } else { preset[1] };
let t2 = if preset[2] == 0 { d2 } else { preset[2] };
let t3 = if preset[3] == 0 { d3 } else { preset[3] };
let reset = if preset[4] == 0 { RESET_DEFAULT } else { preset[4] };
if !(near < t1 && t1 <= t2 && t2 <= t3 && t3 <= maxval) || !(3..=255).contains(&reset) {
return Err(bad("invalid threshold or RESET preset"));
}
let range = (maxval + 2 * near) / (2 * near + 1) + 1;
let bpp = ceil_log2(maxval + 1).max(2);
Ok(Params { maxval, near, range, qbpp: ceil_log2(range), limit: 2 * (bpp + bpp.max(8)), t1, t2, t3, reset })
}
}
/// Adaptive state of one scan: contexts, bias and the run index.
struct State {
a: [i32; CONTEXTS],
b: [i32; CONTEXTS],
c: [i32; CONTEXTS],
n: [i32; CONTEXTS],
nn: [i32; 2],
run_index: usize,
}
impl State {
fn new(p: &Params) -> State {
let a0 = ((p.range + 32) / 64).max(2);
State { a: [a0; CONTEXTS], b: [0; CONTEXTS], c: [0; CONTEXTS], n: [1; CONTEXTS], nn: [0; 2], run_index: 0 }
}
}
fn quantise_gradient(d: i32, p: &Params) -> i32 {
if d <= -p.t3 {
-4
} else if d <= -p.t2 {
-3
} else if d <= -p.t1 {
-2
} else if d < -p.near {
-1
} else if d <= p.near {
0
} else if d < p.t1 {
1
} else if d < p.t2 {
2
} else if d < p.t3 {
3
} else {
4
}
}
fn predict(ra: i32, rb: i32, rc: i32) -> i32 {
if rc >= ra.max(rb) {
ra.min(rb)
} else if rc <= ra.min(rb) {
ra.max(rb)
} else {
ra + rb - rc
}
}
/// The error quantised for `NEAR` and reduced into the modulo range, as the encoder codes it.
fn reduce(mut e: i32, p: &Params) -> i32 {
if p.near > 0 {
e = if e > 0 { (e + p.near) / (2 * p.near + 1) } else { -(p.near - e) / (2 * p.near + 1) };
}
if e < 0 {
e += p.range;
}
if e >= (p.range + 1) / 2 {
e -= p.range;
}
e
}
/// The reconstructed sample for a decoded (sign-adjusted) error.
fn reconstruct(px: i32, sign: i32, e: i32, p: &Params) -> i32 {
let mut r = px + sign * e * (2 * p.near + 1);
if r < -p.near {
r += p.range * (2 * p.near + 1);
} else if r > p.maxval + p.near {
r -= p.range * (2 * p.near + 1);
}
r.clamp(0, p.maxval)
}
fn golomb_k(n: i32, a: i32) -> u32 {
let mut k = 0;
while (i64::from(n) << k) < i64::from(a) {
k += 1;
}
k
}
/// Bits of the entropy-coded segment, with T.87's stuffing: after an `0xFF` byte the next byte
/// carries only 7 bits.
struct BitReader<'a> {
data: &'a [u8],
pos: usize,
cur: u32,
left: u32,
prev_ff: bool,
}
impl<'a> BitReader<'a> {
fn new(data: &'a [u8]) -> Self {
BitReader { data, pos: 0, cur: 0, left: 0, prev_ff: false }
}
fn bit(&mut self) -> Result<u32, CodecError> {
if self.left == 0 {
let byte = *self.data.get(self.pos).ok_or_else(|| bad("the entropy-coded data ends early"))?;
self.pos += 1;
if self.prev_ff {
if byte & 0x80 != 0 {
return Err(bad("a marker inside entropy-coded data"));
}
self.cur = u32::from(byte);
self.left = 7;
} else {
self.cur = u32::from(byte);
self.left = 8;
}
self.prev_ff = byte == 0xFF;
}
self.left -= 1;
Ok((self.cur >> self.left) & 1)
}
fn bits(&mut self, n: u32) -> Result<u32, CodecError> {
let mut v = 0;
for _ in 0..n {
v = v << 1 | self.bit()?;
}
Ok(v)
}
/// A limited-length Golomb code: the mapped error.
fn golomb(&mut self, k: u32, limit: u32, qbpp: u32) -> Result<i32, CodecError> {
let max_zeros = limit.checked_sub(qbpp + 1).ok_or_else(|| bad("invalid LIMIT"))?;
let mut zeros = 0;
while self.bit()? == 0 {
zeros += 1;
if zeros > max_zeros {
return Err(bad("a Golomb code is longer than LIMIT"));
}
}
let v = if zeros < max_zeros { (zeros << k) + self.bits(k)? } else { self.bits(qbpp)? + 1 };
i32::try_from(v).map_err(|_| bad("mapped error out of range"))
}
}
/// Decode one component scan of `w` x `h` samples into `out` (row-major).
fn decode_scan(data: &[u8], w: usize, h: usize, p: &Params, out: &mut [u16]) -> Result<(), CodecError> {
let mut r = BitReader::new(data);
let mut st = State::new(p);
let mut prev = vec![0i32; w + 2];
let mut cur = vec![0i32; w + 2];
for y in 0..h {
// Ra at the first sample is Rb; the slot at index 0 is Rc there, left over from the line above.
cur[0] = prev[1];
if y > 0 {
prev[w + 1] = prev[w];
}
let mut x = 0usize;
while x < w {
let (ra, rb, rc, rd) = (cur[x], prev[x + 1], prev[x], if y == 0 { 0 } else { prev[x + 2] });
let (q1, q2, q3) = (quantise_gradient(rd - rb, p), quantise_gradient(rb - rc, p), quantise_gradient(rc - ra, p));
if q1 == 0 && q2 == 0 && q3 == 0 {
x = decode_run(&mut r, &mut st, p, &prev, &mut cur, ra, x, w)?;
continue;
}
let (sign, q1, q2, q3) = if q1 < 0 || (q1 == 0 && (q2 < 0 || (q2 == 0 && q3 < 0))) { (-1, -q1, -q2, -q3) } else { (1, q1, q2, q3) };
let q = (q1 * 81 + (q2 + 4) * 9 + (q3 + 4)) as usize;
let k = golomb_k(st.n[q], st.a[q]);
let m = r.golomb(k, p.limit, p.qbpp)?;
let swap = p.near == 0 && k == 0 && 2 * st.b[q] <= -st.n[q];
let e = if swap {
if m & 1 == 1 { (m - 1) >> 1 } else { -(m >> 1) - 1 }
} else if m & 1 == 0 {
m >> 1
} else {
-((m + 1) >> 1)
};
let px = (predict(ra, rb, rc) + sign * st.c[q]).clamp(0, p.maxval);
let rx = reconstruct(px, sign, e, p);
update_regular(&mut st, q, e, p);
cur[x + 1] = rx;
x += 1;
}
let row = &mut out[y * w..(y + 1) * w];
for (o, &v) in row.iter_mut().zip(&cur[1..=w]) {
*o = v as u16;
}
// The line just decoded becomes the line above; its slot 0 is the Rc of the next line's first sample.
std::mem::swap(&mut prev, &mut cur);
}
Ok(())
}
fn update_regular(st: &mut State, q: usize, e: i32, p: &Params) {
st.b[q] += e * (2 * p.near + 1);
st.a[q] += e.abs();
if st.n[q] == p.reset {
st.a[q] >>= 1;
st.b[q] = if st.b[q] >= 0 { st.b[q] >> 1 } else { -((1 - st.b[q]) >> 1) };
st.n[q] >>= 1;
}
st.n[q] += 1;
if st.b[q] <= -st.n[q] {
if st.c[q] > MIN_C {
st.c[q] -= 1;
}
st.b[q] += st.n[q];
if st.b[q] <= -st.n[q] {
st.b[q] = -st.n[q] + 1;
}
} else if st.b[q] > 0 {
if st.c[q] < MAX_C {
st.c[q] += 1;
}
st.b[q] -= st.n[q];
if st.b[q] > 0 {
st.b[q] = 0;
}
}
}
/// Run-interruption variables update shared by both directions.
fn update_run(st: &mut State, q: usize, e: i32, em: i32, ri_type: i32, p: &Params) {
let i = q - RI_BASE;
if e < 0 {
st.nn[i] += 1;
}
st.a[q] += (em + 1 - ri_type) >> 1;
if st.n[q] == p.reset {
st.a[q] >>= 1;
st.n[q] >>= 1;
st.nn[i] >>= 1;
}
st.n[q] += 1;
}
/// The run-interruption Golomb parameter and the mapping flag of an error.
fn run_k(st: &State, q: usize, ri_type: i32) -> u32 {
let temp = if ri_type == 1 { st.a[q] + (st.n[q] >> 1) } else { st.a[q] };
golomb_k(st.n[q], temp)
}
#[allow(clippy::too_many_arguments)]
fn decode_run(
r: &mut BitReader,
st: &mut State,
p: &Params,
prev: &[i32],
cur: &mut [i32],
ra: i32,
x: usize,
w: usize,
) -> Result<usize, CodecError> {
let remaining = w - x;
let mut run = 0usize;
while r.bit()? == 1 {
let step = 1usize << J[st.run_index];
let count = step.min(remaining - run);
run += count;
if count == step && st.run_index < 31 {
st.run_index += 1;
}
if run == remaining {
break;
}
}
if run < remaining {
let rest = r.bits(J[st.run_index])? as usize;
run += rest;
if run > remaining {
return Err(bad("a run passes the end of the line"));
}
}
for v in &mut cur[x + 1..x + 1 + run] {
*v = ra;
}
if run == remaining {
return Ok(w);
}
// The sample that ended the run: its own Rb, the sample above it.
let rb = prev[x + run + 1];
let ri_type = i32::from((ra - rb).abs() <= p.near);
let q = RI_BASE + ri_type as usize;
let k = run_k(st, q, ri_type);
let limit = p.limit - J[st.run_index] - 1;
let em = r.golomb(k, limit, p.qbpp)?;
let tmp = em + ri_type;
let cond = k == 0 && 2 * st.nn[ri_type as usize] < st.n[q];
let map = tmp & 1;
let mag = (tmp + map) / 2;
let e = if (cond && map == 1) || (!cond && map == 0) { mag } else { -mag };
let (px, sign) = if ri_type == 1 { (ra, 1) } else { (rb, if ra > rb { -1 } else { 1 }) };
// The decoder holds the sign-adjusted error; the sign flips the reconstruction.
let rx = reconstruct(px, sign, e, p);
update_run(st, q, e, em, ri_type, p);
if st.run_index > 0 {
st.run_index -= 1;
}
cur[x + run + 1] = rx;
Ok(x + run + 1)
}
// ---- encoder ----
struct BitWriter {
out: Vec<u8>,
cur: u32,
used: u32,
cap: u32,
}
impl BitWriter {
fn new() -> Self {
BitWriter { out: Vec::new(), cur: 0, used: 0, cap: 8 }
}
fn put(&mut self, value: u32, n: u32) {
for i in (0..n).rev() {
// A run of more than 32 zero bits (a long escape code) has no bits of `value` to shift out.
let bit = if i < 32 { (value >> i) & 1 } else { 0 };
self.cur = self.cur << 1 | bit;
self.used += 1;
if self.used == self.cap {
let byte = self.cur as u8;
self.out.push(byte);
self.cap = if byte == 0xFF { 7 } else { 8 };
self.cur = 0;
self.used = 0;
}
}
}
/// Pad the last byte with zero bits; a closing 0xFF is followed by a zero byte.
fn finish(mut self) -> Vec<u8> {
if self.used > 0 {
let pad = self.cap - self.used;
self.put(0, pad);
}
if self.out.last() == Some(&0xFF) {
self.out.push(0);
}
self.out
}
fn golomb(&mut self, m: i32, k: u32, limit: u32, qbpp: u32) {
let m = m as u32;
let max_zeros = limit - qbpp - 1;
let q = m >> k;
if q < max_zeros {
self.put(0, q);
self.put(1, 1);
self.put(m & ((1 << k) - 1), k);
} else {
self.put(0, max_zeros);
self.put(1, 1);
self.put(m - 1, qbpp);
}
}
}
fn encode_scan(plane: &[u16], w: usize, h: usize, p: &Params) -> Vec<u8> {
let mut wr = BitWriter::new();
let mut st = State::new(p);
let mut prev = vec![0i32; w + 2];
let mut cur = vec![0i32; w + 2];
for y in 0..h {
cur[0] = prev[1];
if y > 0 {
prev[w + 1] = prev[w];
}
let line = &plane[y * w..(y + 1) * w];
let mut x = 0usize;
while x < w {
let (ra, rb, rc, rd) = (cur[x], prev[x + 1], prev[x], if y == 0 { 0 } else { prev[x + 2] });
let ix = i32::from(line[x]);
let (q1, q2, q3) = (quantise_gradient(rd - rb, p), quantise_gradient(rb - rc, p), quantise_gradient(rc - ra, p));
if q1 == 0 && q2 == 0 && q3 == 0 {
x = encode_run(&mut wr, &mut st, p, line, &prev, &mut cur, ra, x);
continue;
}
let (sign, q1, q2, q3) = if q1 < 0 || (q1 == 0 && (q2 < 0 || (q2 == 0 && q3 < 0))) { (-1, -q1, -q2, -q3) } else { (1, q1, q2, q3) };
let q = (q1 * 81 + (q2 + 4) * 9 + (q3 + 4)) as usize;
let px = (predict(ra, rb, rc) + sign * st.c[q]).clamp(0, p.maxval);
let e = reduce(sign * (ix - px), p);
let k = golomb_k(st.n[q], st.a[q]);
let swap = p.near == 0 && k == 0 && 2 * st.b[q] <= -st.n[q];
let m = if swap {
if e >= 0 { 2 * e + 1 } else { -2 * (e + 1) }
} else if e >= 0 {
2 * e
} else {
-2 * e - 1
};
wr.golomb(m, k, p.limit, p.qbpp);
cur[x + 1] = reconstruct(px, sign, e, p);
update_regular(&mut st, q, e, p);
x += 1;
}
std::mem::swap(&mut prev, &mut cur);
}
wr.finish()
}
#[allow(clippy::too_many_arguments)]
fn encode_run(wr: &mut BitWriter, st: &mut State, p: &Params, line: &[u16], prev: &[i32], cur: &mut [i32], ra: i32, x: usize) -> usize {
let w = line.len();
let mut run = 0usize;
while x + run < w && (i32::from(line[x + run]) - ra).abs() <= p.near {
cur[x + run + 1] = ra;
run += 1;
}
let mut count = run;
while count >= 1usize << J[st.run_index] {
wr.put(1, 1);
count -= 1usize << J[st.run_index];
if st.run_index < 31 {
st.run_index += 1;
}
}
if x + run == w {
if count > 0 {
wr.put(1, 1);
}
return w;
}
wr.put(0, 1);
wr.put(count as u32, J[st.run_index]);
let ix = i32::from(line[x + run]);
let rb = prev[x + run + 1];
let ri_type = i32::from((ra - rb).abs() <= p.near);
let q = RI_BASE + ri_type as usize;
let (px, sign) = if ri_type == 1 { (ra, 1) } else { (rb, if ra > rb { -1 } else { 1 }) };
let e = reduce(sign * (ix - px), p);
let k = run_k(st, q, ri_type);
let n_neg = st.nn[ri_type as usize];
let map = i32::from((k == 0 && e > 0 && 2 * n_neg < st.n[q]) || (e < 0 && 2 * n_neg >= st.n[q]) || (e < 0 && k != 0));
let em = 2 * e.abs() - ri_type - map;
wr.golomb(em, k, p.limit - J[st.run_index] - 1, p.qbpp);
cur[x + run + 1] = reconstruct(px, sign, e, p);
update_run(st, q, e, em, ri_type, p);
if st.run_index > 0 {
st.run_index -= 1;
}
x + run + 1
}
/// Writes a lossless JPEG-LS file: 8 or 16 bits, gray or RGB, one scan per component.
pub(crate) fn encode(src: &Image, plan: Plan) -> Result<Vec<u8>, CodecError> {
let enc = |msg: String| CodecError::encode(F, msg);
let img = src.converted(plan.layout, plan.sample);
let nc = match img.layout() {
ChannelLayout::Gray => 1,
ChannelLayout::Rgb => 3,
l => return Err(enc(format!("no JPEG-LS layout for {l:?}"))),
};
let precision: u32 = match img.sample_type() {
SampleType::U8 => 8,
SampleType::U16 => 16,
s => return Err(enc(format!("JPEG-LS stores 8 or 16 bits per sample, not {s:?}"))),
};
let (w, h) = img.dimensions();
let (Ok(w16), Ok(h16)) = (u16::try_from(w), u16::try_from(h)) else {
return Err(enc(format!("dimensions exceed 65535x65535: {w}x{h}")));
};
let (wu, hu) = (w as usize, h as usize);
let data = img.data();
if data.len() != wu * hu * nc * (precision as usize / 8) {
return Err(enc("the image has the wrong number of samples".into()));
}
let params = Params::new(precision, 0, [0; 5]).map_err(|_| enc("invalid coding parameters".into()))?;
let mut out = vec![0xFF, 0xD8, 0xFF, SOF55];
out.extend_from_slice(&((8 + 3 * nc) as u16).to_be_bytes());
out.push(precision as u8);
out.extend_from_slice(&h16.to_be_bytes());
out.extend_from_slice(&w16.to_be_bytes());
out.push(nc as u8);
for c in 0..nc {
out.extend_from_slice(&[c as u8 + 1, 0x11, 0]);
}
let mut plane = vec![0u16; wu * hu];
for c in 0..nc {
for (i, v) in plane.iter_mut().enumerate() {
let at = i * nc + c;
*v = if precision == 8 { u16::from(data[at]) } else { u16::from_ne_bytes([data[2 * at], data[2 * at + 1]]) };
}
out.extend_from_slice(&[0xFF, 0xDA, 0, 8, 1, c as u8 + 1, 0, 0, 0, 0]);
out.extend_from_slice(&encode_scan(&plane, wu, hu, &params));
}
out.extend_from_slice(&[0xFF, 0xD9]);
Ok(out)
}
struct Frame {
precision: u32,
width: usize,
height: usize,
components: Vec<u8>,
}
fn be16(b: &[u8], i: usize) -> Result<usize, CodecError> {
b.get(i..i + 2).map(|s| usize::from(u16::from_be_bytes([s[0], s[1]]))).ok_or_else(|| bad("truncated header"))
}
pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result<Image, CodecError> {
if !looks_like_jpegls(b) {
return Err(bad("not a JPEG-LS file"));
}
let mut pos = 2;
let mut frame: Option<Frame> = None;
let mut preset = [0i32; 5];
let mut planes: Vec<Vec<u16>> = Vec::new();
let mut scans_done = 0;
loop {
// Find the next marker.
while b.get(pos) != Some(&0xFF) {
if pos >= b.len() {
return finish(frame, planes, scans_done);
}
pos += 1;
}
while b.get(pos + 1) == Some(&0xFF) {
pos += 1;
}
let Some(&marker) = b.get(pos + 1) else { return finish(frame, planes, scans_done) };
if marker == 0xD9 {
return finish(frame, planes, scans_done);
}
if marker == 0x00 || (0xD0..=0xD7).contains(&marker) || marker == 0x01 {
pos += 2;
continue;
}
let len = be16(b, pos + 2)?;
let seg = b.get(pos + 4..pos + 2 + len).ok_or_else(|| bad("truncated marker segment"))?;
match marker {
SOF55 => {
if frame.is_some() || seg.len() < 6 {
return Err(bad("bad or repeated frame header"));
}
let (precision, height, width, nf) = (u32::from(seg[0]), be16(seg, 1)?, be16(seg, 3)?, usize::from(seg[5]));
if !(2..=16).contains(&precision) || width == 0 || height == 0 || !matches!(nf, 1 | 3) || seg.len() < 6 + 3 * nf {
return Err(bad("unsupported frame header"));
}
if height == 0 {
return Err(CodecError::unsupported(F, "a frame height set later by a DNL marker"));
}
let layout = if nf == 1 { ChannelLayout::Gray } else { ChannelLayout::Rgb };
let sample = if precision <= 8 { SampleType::U8 } else { SampleType::U16 };
limits.check(width as u32, height as u32, layout, sample)?;
let components = (0..nf).map(|i| seg[6 + 3 * i]).collect();
frame = Some(Frame { precision, width, height, components });
}
LSE => {
if seg.first() == Some(&1) && seg.len() >= 11 {
for (i, p) in preset.iter_mut().enumerate() {
*p = be16(seg, 1 + 2 * i)? as i32;
}
} else if seg.first() != Some(&1) {
return Err(CodecError::unsupported(F, "mapping tables and colour transforms (LSE)"));
}
}
0xDA => {
let f = frame.as_ref().ok_or_else(|| bad("a scan before the frame header"))?;
let ns = usize::from(*seg.first().ok_or_else(|| bad("empty scan header"))?);
if seg.len() < 1 + 2 * ns + 3 || ns != 1 {
return Err(CodecError::unsupported(F, "interleaved scans (ILV 1 and 2)"));
}
let (cs, tm, near, ilv) = (seg[1], seg[2], i32::from(seg[3]), seg[4]);
if tm != 0 {
return Err(CodecError::unsupported(F, "mapping tables"));
}
if ilv != 0 && f.components.len() > 1 {
return Err(CodecError::unsupported(F, "interleaved scans (ILV 1 and 2)"));
}
if seg[5] & 0x0f != 0 {
return Err(CodecError::unsupported(F, "a point transform"));
}
let idx = f.components.iter().position(|&c| c == cs).ok_or_else(|| bad("a scan names an unknown component"))?;
if planes.len() <= idx {
planes.resize(f.components.len(), Vec::new());
}
if !planes[idx].is_empty() {
return Err(bad("a component is coded twice"));
}
let params = Params::new(f.precision, near, preset)?;
let start = pos + 2 + len;
// The scan ends at the next real marker: an 0xFF followed by a byte with its top bit set.
let mut end = start;
while end < b.len() {
if b[end] == 0xFF && b.get(end + 1).is_none_or(|&n| n & 0x80 != 0) {
break;
}
end += 1;
}
let mut samples = Vec::new();
samples.try_reserve_exact(f.width * f.height).map_err(|_| bad("pixel buffer is too large"))?;
samples.resize(f.width * f.height, 0u16);
decode_scan(&b[start..end], f.width, f.height, &params, &mut samples)?;
planes[idx] = samples;
scans_done += 1;
pos = end;
continue;
}
_ => {}
}
pos += 2 + len;
}
}
fn finish(frame: Option<Frame>, planes: Vec<Vec<u16>>, scans: usize) -> Result<Image, CodecError> {
let f = frame.ok_or_else(|| bad("no frame header"))?;
if scans != f.components.len() || planes.iter().any(Vec::is_empty) || planes.len() != f.components.len() {
return Err(bad("the file ends before every component is coded"));
}
let (w, h, nc) = (f.width, f.height, f.components.len());
let layout = if nc == 1 { ChannelLayout::Gray } else { ChannelLayout::Rgb };
let p = f.precision;
let scale = |v: u16| -> u16 {
if p == 16 {
v
} else {
let v = u32::from(v);
((v << (16 - p)) | (v >> (2 * p).saturating_sub(16).min(15))) as u16
}
};
if p <= 8 {
let to8 = |v: u16| -> u8 { if p == 8 { v as u8 } else { (scale(v) >> 8) as u8 } };
let mut data = Vec::with_capacity(w * h * nc);
for i in 0..w * h {
for plane in &planes {
data.push(to8(plane[i]));
}
}
Image::from_u8(w as u32, h as u32, layout, data)
} else {
let mut data = Vec::with_capacity(w * h * nc);
for i in 0..w * h {
for plane in &planes {
data.push(scale(plane[i]));
}
}
Image::from_u16(w as u32, h as u32, layout, &data)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn noise_u16(n: usize, seed: &mut u32, mask: u32) -> Vec<u16> {
(0..n)
.map(|_| {
*seed ^= *seed << 13;
*seed ^= *seed >> 17;
*seed ^= *seed << 5;
(*seed & mask) as u16
})
.collect()
}
fn image(w: u32, h: u32, layout: ChannelLayout, wide: bool, kind: u8) -> Image {
let n = w as usize * h as usize * layout.channels();
let mut seed = 0x1234_5679u32;
let samples: Vec<u16> = match kind {
0 => noise_u16(n, &mut seed, if wide { 0xFFFF } else { 0xFF }),
1 => vec![if wide { 40_000 } else { 100 }; n],
_ => (0..n).map(|i| if wide { ((i / 3) * 37 % 65_536) as u16 } else { ((i / 3) % 251) as u16 }).collect(),
};
if wide {
Image::from_u16(w, h, layout, &samples).unwrap()
} else {
Image::from_u8(w, h, layout, samples.iter().map(|&v| v as u8).collect()).unwrap()
}
}
fn plan(img: &Image) -> Plan {
Plan { layout: img.layout(), sample: img.sample_type() }
}
#[test]
fn round_trips_noise_flat_and_smooth_images() {
for layout in [ChannelLayout::Gray, ChannelLayout::Rgb] {
for wide in [false, true] {
for kind in 0..3 {
// Widths around the run-length steps, and single-pixel dimensions.
for (w, h) in [(1, 1), (1, 9), (2, 3), (7, 5), (33, 4), (300, 3), (1025, 2)] {
let img = image(w, h, layout, wide, kind);
let bytes = encode(&img, plan(&img)).unwrap();
assert!(looks_like_jpegls(&bytes));
let back = decode(&bytes, &Limits::default()).unwrap_or_else(|e| panic!("{layout:?} wide={wide} kind={kind} {w}x{h}: {e}"));
assert_eq!(back.data(), img.data(), "{layout:?} wide={wide} kind={kind} {w}x{h}");
}
}
}
}
}
#[test]
fn default_parameters_follow_the_standard() {
let p = Params::new(8, 0, [0; 5]).unwrap();
assert_eq!((p.maxval, p.range, p.qbpp, p.limit, p.t1, p.t2, p.t3, p.reset), (255, 256, 8, 32, 3, 7, 21, 64));
let p = Params::new(16, 0, [0; 5]).unwrap();
assert_eq!((p.maxval, p.range, p.qbpp, p.limit, p.t1, p.t2, p.t3), (65535, 65536, 16, 64, 18, 67, 276));
let p = Params::new(8, 3, [0; 5]).unwrap();
assert_eq!((p.range, p.t1), (38, 12)); // RANGE = floor((255 + 2 * 3) / 7) + 1
assert!(Params::new(8, 200, [0; 5]).is_err());
}
#[test]
fn detection_tells_jpeg_ls_from_jpeg() {
let img = image(4, 4, ChannelLayout::Gray, false, 0);
let ls = encode(&img, plan(&img)).unwrap();
assert!(looks_like_jpegls(&ls));
// A baseline JPEG starts SOI, APP0 / DQT, ... SOF0: not JPEG-LS.
assert!(!looks_like_jpegls(&[0xFF, 0xD8, 0xFF, 0xE0, 0, 4, 0, 0, 0xFF, 0xC0, 0, 11]));
assert!(!looks_like_jpegls(&[0xFF, 0xD8, 0xFF, 0xC0, 0, 11]));
// SOF55 after an application segment still is.
assert!(looks_like_jpegls(&[0xFF, 0xD8, 0xFF, 0xE8, 0, 4, 0, 0, 0xFF, 0xF7, 0, 11]));
assert!(!looks_like_jpegls(&[0xFF, 0xD8]));
}
#[test]
fn interleaved_scans_and_tables_are_unsupported() {
let img = image(8, 4, ChannelLayout::Rgb, false, 2);
let good = encode(&img, plan(&img)).unwrap();
// The scan header body is Ns, Cs, Tm, NEAR, ILV, point transform, after the marker and length.
let sos = good.windows(2).position(|w| w == [0xFF, 0xDA]).unwrap() + 4;
let mut line = good.clone();
line[sos + 4] = 1;
assert!(matches!(decode(&line, &Limits::default()), Err(CodecError::Unsupported { .. })));
let mut mapped = good.clone();
mapped[sos + 2] = 1;
assert!(matches!(decode(&mapped, &Limits::default()), Err(CodecError::Unsupported { .. })));
let mut transform = good;
transform[sos + 5] = 1;
assert!(matches!(decode(&transform, &Limits::default()), Err(CodecError::Unsupported { .. })));
}
#[test]
fn hostile_input_is_an_error_not_a_panic() {
for (w, h, layout, wide) in [(23, 9, ChannelLayout::Gray, false), (11, 7, ChannelLayout::Rgb, true)] {
let img = image(w, h, layout, wide, 0);
let good = encode(&img, plan(&img)).unwrap();
for len in 0..good.len() {
let _ = decode(&good[..len], &Limits::default());
}
// Flip every bit of the entropy-coded data and of the headers, one at a time.
for i in 0..good.len() {
for bit in 0..8 {
let mut c = good.clone();
c[i] ^= 1 << bit;
let _ = decode(&c, &Limits::default());
}
}
}
// A huge frame is stopped by the limits or the length check before any allocation.
let img = image(4, 4, ChannelLayout::Gray, false, 0);
let mut huge = encode(&img, plan(&img)).unwrap();
let sof = huge.windows(2).position(|w| w == [0xFF, 0xF7]).unwrap();
huge[sof + 5..sof + 9].copy_from_slice(&[0xFF, 0xFF, 0xFF, 0xFF]);
assert!(decode(&huge, &Limits::default()).is_err());
}
}
+58 -7
View File
@@ -141,12 +141,12 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
/// Reads the header and refuses what [`decode`] refuses before any pixel is decoded: sizes
/// past `limits`, and a file too small for the image it declares.
pub fn new(bytes: B, limits: &Limits) -> Result<Self, CodecError> {
Self::open(bytes, limits, true)
Self::open(bytes, limits, true, false)
}
/// [`PngDecodeRows::new`], optionally without reserving the whole image: a caller that hands
/// the rows on as they come ([`decode_rows`]) never holds them all.
fn open(bytes: B, limits: &Limits, reserve: bool) -> Result<Self, CodecError> {
fn open(bytes: B, limits: &Limits, reserve: bool, bounded_stream: bool) -> Result<Self, CodecError> {
let at = std::sync::Arc::new(std::sync::atomic::AtomicU64::new(0));
let bytes = SharedInput(std::sync::Arc::new(bytes));
let input = Tracked { cursor: Cursor::new(bytes.clone()), at: at.clone() };
@@ -187,7 +187,14 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
let (width, height) = info.frame_control.map_or_else(|| info.size(), |f| (f.width, f.height));
let line = reader.output_line_size(width).ok_or_else(|| err("image too large"))?;
// The output layout is known: charge its real bytes per pixel, not RGBA16's worst case.
limits.check(width, height, layout, sample)?;
if bounded_stream {
limits.check_size(width, height)?;
if line > limits.alloc_usize() {
return Err(CodecError::LimitExceeded("one PNG row exceeds max_alloc".into()));
}
} else {
limits.check(width, height, layout, sample)?;
}
let height = usize::try_from(height).map_err(|_| err("image too large"))?;
if width == 0 || height == 0 {
return Err(err("the image is empty"));
@@ -234,11 +241,35 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
/// decode the whole image after all (an interlaced file) calls
/// [`PngDecodeRows::reserve_output`] before [`PngDecodeRows::step`].
pub fn new_streaming(bytes: B, limits: &Limits) -> Result<Self, CodecError> {
Self::open(bytes, limits, false)
Self::open(bytes, limits, false, false)
}
/// Opens a bounded row stream without charging a full image that is never retained.
/// Dimension, pixel-count, plausibility, decoder and metadata limits remain unchanged;
/// `max_alloc` also bounds each row group. It is not a total process-memory limit.
/// Unlike [`Self::new_streaming`], a streamable image may exceed the full-image budget.
/// Non-streamable images still require that budget, as do [`Self::step`] and
/// [`Self::reserve_output`]. The caller must bound any output it retains in its sink.
pub fn new_bounded_streaming(bytes: B, limits: &Limits) -> Result<Self, CodecError> {
let decoder = Self::open(bytes, limits, false, true)?;
if !decoder.streamable() {
decoder.check_full_output()?;
}
Ok(decoder)
}
fn check_full_output(&self) -> Result<(), CodecError> {
let height = u32::try_from(self.height).map_err(|_| err("image too large"))?;
self.limits.check(self.width, height, self.layout, self.sample)?;
if self.size > self.limits.alloc_usize() {
return Err(CodecError::LimitExceeded("PNG output exceeds max_alloc".into()));
}
Ok(())
}
/// Reserves the buffer [`PngDecodeRows::step`] decodes the whole image into.
pub fn reserve_output(&mut self) -> Result<(), CodecError> {
self.check_full_output()?;
let size = self.size;
self.buf.try_reserve_exact(size).map_err(|_| CodecError::LimitExceeded(format!("cannot allocate {size} bytes for the image")))
}
@@ -271,6 +302,7 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
/// Decodes at least one row (the whole image if it is interlaced), then goes on while `more()`
/// returns true. `Some` once the image is complete, after which the decoder is spent.
pub fn step(&mut self, more: &mut dyn FnMut() -> bool) -> Result<Option<Image>, CodecError> {
self.check_full_output()?;
if self.done {
return Err(err("the image was already decoded"));
}
@@ -338,7 +370,9 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
/// `more()` returns true; `Some` with the extras once the file is read to its end, with the
/// resolution a format that lacks one takes from its EXIF or XMP. A damaged file fails with
/// the error [`decode`] gives, after however many rows were delivered. An orientation (an
/// `eXIf` after the image data may set one) is for the caller to apply.
/// `eXIf` after the image data may set one) is for the caller to apply. A new group size
/// must exceed any partial group retained from an earlier yield; otherwise this returns
/// an error without consuming another row.
pub fn step_stream<E: From<CodecError>>(
&mut self,
group: u32,
@@ -348,12 +382,29 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
if self.done {
return Err(err("the image was already decoded").into());
}
let group = usize::try_from(group.max(1)).unwrap_or(usize::MAX);
// Tail EXIF may report an orientation after rows have already been delivered;
// that belongs in the returned extras, not a rejection of metadata continuation.
if self.rows == 0 && !self.tail && !self.streamable() {
return Err(err("this PNG requires whole-image decoding").into());
}
let group = usize::try_from(group.max(1)).unwrap_or(usize::MAX).min(self.height);
if self.rows - self.group_start >= group {
return Err(err("PNG row group is smaller than rows held from the previous step").into());
}
let group_bytes = group.checked_mul(self.line).ok_or_else(|| err("PNG row group is too large"))?;
if group_bytes > self.limits.alloc_usize() {
return Err(CodecError::LimitExceeded("PNG row group exceeds max_alloc".into()).into());
}
if !self.tail {
while self.rows < self.height {
let held = self.rows - self.group_start;
let at = held.checked_mul(self.line).ok_or_else(|| err("image too large"))?;
let end = at.checked_add(self.line).ok_or_else(|| err("image too large"))?;
// A caller may change its group size between yields. Bound the actual held
// bytes as well as the requested group before growing the row buffer.
if end > self.limits.alloc_usize() {
return Err(CodecError::LimitExceeded("PNG row group exceeds max_alloc".into()).into());
}
if self.buf.len() < end {
self.buf
.try_reserve_exact(end - self.buf.len())
@@ -368,7 +419,7 @@ impl<B: AsRef<[u8]>> PngDecodeRows<B> {
to_native_endian(row);
}
self.rows += 1;
if self.rows - self.group_start == group || self.rows == self.height {
if self.rows - self.group_start >= group || self.rows == self.height {
let data = self.buf.get(..end).ok_or_else(|| err("invalid PNG row group"))?;
sink(u32::try_from(self.group_start).map_err(|_| err("image too large"))?, data)?;
self.group_start = self.rows;
+7 -55
View File
@@ -5,66 +5,18 @@
//! ColorSpace = sRGB as sRGB, unless Preferences › File Handling › Ignore EXIF Profile Tag is on.
//! Anything malformed, truncated or missing reads as no tag.
use crate::orientation::{Order, ifd0_entries, tiff_body};
/// IFD0's pointer to the Exif sub-IFD.
const TAG_EXIF_IFD: u16 = 0x8769;
/// The ColorSpace tag in the Exif sub-IFD.
const TAG_COLOR_SPACE: u16 = 0xA001;
const TYPE_SHORT: u16 = 3;
const TYPE_LONG: u16 = 4;
/// TIFF type 13: an IFD offset (some writers use it for sub-IFD pointers).
const TYPE_IFD: u16 = 13;
/// Bytes per classic TIFF IFD entry; EXIF is never BigTIFF.
const ENTRY: usize = 12;
/// No IFD can start inside the 8-byte TIFF header.
const HEADER: usize = 8;
/// The ColorSpace value meaning sRGB.
pub const EXIF_COLOR_SPACE_SRGB: u16 = 1;
/// The EXIF ColorSpace value of a TIFF-structured block (an EXIF payload with or without the
/// `Exif\0\0` prefix), or `None` when it has none or it is malformed.
pub fn exif_color_space(exif: &[u8]) -> Option<u16> {
let b = tiff_body(exif);
let (order, first, count, entry_bytes, big_tiff) = ifd0_entries(b)?;
if big_tiff {
return None;
}
let ptr = find(order, b, first, count, entry_bytes, TAG_EXIF_IFD)?;
if !matches!(order.u16(b, ptr.checked_add(2)?)?, TYPE_LONG | TYPE_IFD) || order.u32(b, ptr.checked_add(4)?)? != 1 {
return None;
}
let ifd = usize::try_from(order.u32(b, ptr.checked_add(8)?)?).ok()?;
if ifd < HEADER {
return None;
}
let n = usize::from(order.u16(b, ifd)?);
let first = ifd.checked_add(2)?;
// The whole table must be present.
if first.checked_add(n.checked_mul(ENTRY)?)? > b.len() {
return None;
}
let e = find(order, b, first, n, ENTRY, TAG_COLOR_SPACE)?;
if order.u32(b, e.checked_add(4)?)? != 1 {
return None;
}
match order.u16(b, e.checked_add(2)?)? {
TYPE_SHORT => order.u16(b, e.checked_add(8)?),
TYPE_LONG => u16::try_from(order.u32(b, e.checked_add(8)?)?).ok(),
_ => None,
}
}
/// Offset of the first entry tagged `tag` in the IFD whose `count` entries start at `first`.
fn find(order: Order, b: &[u8], first: usize, count: usize, entry_bytes: usize, tag: u16) -> Option<usize> {
(0..count).filter_map(|i| first.checked_add(i.checked_mul(entry_bytes)?)).find(|&e| order.u16(b, e) == Some(tag))
}
// Share parsing and malformed-input policy with every craft-metadata caller.
pub use craft_metadata::edit::{EXIF_COLOR_SPACE_SRGB, exif_color_space};
#[cfg(test)]
mod tests {
use super::*;
const TAG_EXIF_IFD: u16 = 0x8769;
const TAG_COLOR_SPACE: u16 = 0xA001;
const TYPE_SHORT: u16 = 3;
const TYPE_LONG: u16 = 4;
/// A little- or big-endian EXIF block: IFD0 holding only the Exif pointer, then an Exif IFD
/// holding `entries` (tag, type, count, value).
fn exif(big_endian: bool, entries: &[(u16, u16, u32, u32)]) -> Vec<u8> {
+12 -2
View File
@@ -45,6 +45,8 @@ pub enum Format {
Iff,
/// JPEG 2000 (JP2 container or raw J2K codestream): read-only; see [`ASYMMETRIC_EXCEPTIONS`].
Jp2,
/// JPEG-LS (`.jls`): lossless and near-lossless gray and RGB.
JpegLs,
}
/// What a format can hold **and** what this crate reads/writes for it.
@@ -116,7 +118,7 @@ const TIFF_LAYOUTS: &[ChannelLayout] = &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::
impl Format {
/// Every format known to the crate (enabled or not).
pub const ALL: [Format; 24] = [
pub const ALL: [Format; 25] = [
Format::Png,
Format::Jpeg,
Format::Jp2,
@@ -141,6 +143,7 @@ impl Format {
Format::Cineon,
Format::Dicom,
Format::Iff,
Format::JpegLs,
];
pub fn caps(self) -> FormatCaps {
@@ -179,6 +182,7 @@ impl Format {
Format::Dicom => "DICOM",
Format::Iff => "Amiga IFF",
Format::Jp2 => "JPEG 2000",
Format::JpegLs => "JPEG-LS",
}
}
@@ -210,6 +214,7 @@ impl Format {
Format::Dicom => &["dcm", "dicom", "dc3"],
Format::Iff => &["iff", "lbm", "ilbm"],
Format::Jp2 => &["jp2", "j2k", "j2c", "jpf", "jpx"],
Format::JpegLs => &["jls"],
}
}
@@ -239,13 +244,14 @@ impl Format {
Format::Dicom => "application/dicom",
Format::Iff => "image/x-iff",
Format::Jp2 => "image/jp2",
Format::JpegLs => "image/jls",
}
}
/// Maximum encodable dimensions, if the format has a hard limit.
pub fn max_dimensions(self) -> Option<(u32, u32)> {
match self {
Format::Jpeg | Format::Gif | Format::Iff => Some((65535, 65535)),
Format::Jpeg | Format::Gif | Format::Iff | Format::JpegLs => Some((65535, 65535)),
Format::WebP => Some((16384, 16384)),
Format::Ico => Some((256, 256)),
_ => None,
@@ -315,6 +321,7 @@ pub fn caps(format: Format) -> FormatCaps {
Format::Cineon => FormatCaps { depths: &[S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base },
Format::Dicom => FormatCaps { read: true, write: false, depths: &[S::U8, S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base },
Format::Iff => FormatCaps { depths: &[S::U8], layouts: &[L::Rgb, L::Rgba], alpha: true, ..base },
Format::JpegLs => FormatCaps { depths: &[S::U8, S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base },
Format::Jp2 => FormatCaps { read: true, write: false, layouts: &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::Cmyk, L::CmykA], icc: true, ..base },
}
}
@@ -326,6 +333,9 @@ pub fn detect(bytes: &[u8]) -> Option<Format> {
if b.starts_with(b"\x89PNG\r\n\x1a\n") {
return Some(Format::Png);
}
if crate::codecs::jpegls::looks_like_jpegls(b) {
return Some(Format::JpegLs);
}
if b.starts_with(&[0xFF, 0xD8, 0xFF]) {
return Some(Format::Jpeg);
}
+82
View File
@@ -0,0 +1,82 @@
//! Validated Samsung SEF trailer repair for JPEGs missing their final EOI marker.
use std::borrow::Cow;
/// Whether the first JPEG image reaches an EOI through its marker and scan structure.
pub fn reaches_eoi(bytes: &[u8]) -> bool {
crate::codecs::jpeg::reaches_eoi(bytes)
}
/// Borrow ordinary input unchanged. For a validated Samsung SEF trailer following an open JPEG
/// scan, remove that trailer and append the missing EOI. The owned copy is made only on repair.
pub fn repair(bytes: &[u8]) -> Cow<'_, [u8]> {
let Some(image) = image_end(bytes).and_then(|end| bytes.get(..end)) else { return Cow::Borrowed(bytes) };
if reaches_eoi(image) {
return Cow::Borrowed(bytes);
}
let mut fixed = Vec::with_capacity(image.len().saturating_add(2));
fixed.extend_from_slice(image);
fixed.extend_from_slice(&[0xff, 0xd9]);
let in_scan = craft_metadata::inspect_jpeg(&fixed).is_some_and(|m| m.first_scan_components > 0) && reaches_eoi(&fixed);
if in_scan { Cow::Owned(fixed) } else { Cow::Borrowed(bytes) }
}
fn image_end(b: &[u8]) -> Option<usize> {
let le32 = |at: usize| b.get(at..at.checked_add(4)?)?.try_into().ok().map(|v| u32::from_le_bytes(v) as usize);
let tail = b.len().checked_sub(8)?;
if b.get(tail.checked_add(4)?..)? != b"SEFT" {
return None;
}
let dir = tail.checked_sub(le32(tail)?)?;
if b.get(dir..dir.checked_add(4)?)? != b"SEFH" {
return None;
}
let count = le32(dir.checked_add(8)?)?;
let entries = dir.checked_add(12)?;
if count == 0 || count > tail.checked_sub(entries)? / 12 {
return None;
}
let mut start = dir;
for i in 0..count {
let entry = entries.checked_add(i.checked_mul(12)?)?;
let block = dir.checked_sub(le32(entry.checked_add(4)?)?)?;
let len = le32(entry.checked_add(8)?)?;
let kind = |at: usize| b.get(at.checked_add(2)?..at.checked_add(4)?);
if len < 4 || block.checked_add(len)? > dir || kind(block)? != kind(entry)? {
return None;
}
start = start.min(block);
}
Some(start)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn repairs_only_valid_sef_after_an_open_scan() {
let image = [0xff, 0xd8, 0xff, 0xc0, 0, 8, 8, 0, 1, 0, 1, 1, 0xff, 0xda, 0, 3, 1, 0x12, 0xff, 0, 0x34];
let mut b = image.to_vec();
let block = [0, 0, 0xe0, 0x08, 1, 2, 3, 4];
b.extend_from_slice(&block);
b.extend_from_slice(b"SEFH");
b.extend_from_slice(&106u32.to_le_bytes());
b.extend_from_slice(&1u32.to_le_bytes());
b.extend_from_slice(&[0, 0, 0xe0, 0x08]);
b.extend_from_slice(&(block.len() as u32).to_le_bytes());
b.extend_from_slice(&(block.len() as u32).to_le_bytes());
b.extend_from_slice(&24u32.to_le_bytes());
b.extend_from_slice(b"SEFT");
let mut expected = image.to_vec();
expected.extend_from_slice(&[0xff, 0xd9]);
assert_eq!(repair(&b).as_ref(), expected);
assert!(matches!(repair(&image), Cow::Borrowed(_)));
b[image.len() + 2] = 0;
assert!(matches!(repair(&b), Cow::Borrowed(_)));
}
#[test]
fn eoi_requires_valid_lengths_and_skips_stuffed_bytes() {
assert!(reaches_eoi(&[0xff, 0xd8, 0xff, 0, 0xff, 0xd9]));
assert!(!reaches_eoi(&[0xff, 0xd8, 0xff, 0xe1, 0, 1, 0xff, 0xd9]));
assert!(!reaches_eoi(&[0xff, 0xd8, 0xff, 0xe1, 0, 4, 0xff, 0xd9]));
}
}
+6 -1
View File
@@ -16,6 +16,7 @@
mod allocation;
pub mod apng;
pub mod bmp_probe;
pub mod cicp;
mod codecs;
mod error;
@@ -25,9 +26,11 @@ mod fidelity;
mod format;
mod image;
mod inspection;
pub mod jpeg_sef;
mod lab;
mod options;
pub mod orientation;
pub mod png_probe;
pub mod resolution;
pub mod source_settings;
pub mod web;
@@ -63,7 +66,7 @@ pub use crate::resolution::{exif_resolution, export_exif, export_xmp, photoshop_
pub use crate::source_settings::{WebpEncoding, jpeg_quality, webp_encoding};
pub use half::f16;
use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jxl, pcx, png, pnm, tiff, via_image, webp, xpm};
use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jpegls, jxl, pcx, png, pnm, tiff, via_image, webp, xpm};
/// Detect the format and decode with default [`Limits`].
pub fn decode(bytes: &[u8]) -> Result<Image, CodecError> {
@@ -102,6 +105,7 @@ pub fn decode_as_with(format: Format, bytes: &[u8], opts: &DecodeOptions) -> Res
Format::Cineon => dpx::decode_cineon(bytes, l),
Format::Dicom => dicom::decode(bytes, l),
Format::Iff => iff::decode(bytes, l),
Format::JpegLs => jpegls::decode(bytes, l),
Format::OpenExr => exr::decode(bytes, l),
Format::Heif => heif::decode(bytes, l, opts.keep_orientation),
Format::Jp2 => jp2::decode(bytes, l),
@@ -476,6 +480,7 @@ pub fn encode(image: &Image, format: Format, opts: &EncodeOptions) -> Result<Vec
Format::Cineon => dpx::encode_cineon(image, plan),
Format::Dicom => Err(CodecError::unsupported(format, "DICOM is import-only; save as TIFF or PNG instead")),
Format::Iff => iff::encode(image, plan),
Format::JpegLs => jpegls::encode(image, plan),
Format::OpenExr => exr::encode(image, plan, opts),
Format::Heif => Err(CodecError::unsupported(format, "encoding is not available in this build")),
Format::Jp2 => Err(CodecError::unsupported(format, "JPEG 2000 is import-only; save as PNG or TIFF instead")),
+5 -206
View File
@@ -20,213 +20,12 @@ use std::borrow::Cow;
use crate::error::CodecError;
use crate::image::Image;
/// The TIFF/EXIF Orientation tag.
const TAG_ORIENTATION: u16 = 274;
/// Field types accepted for the Orientation tag: SHORT (the spec) and LONG
/// (written by some cameras and tools).
const TYPE_SHORT: u16 = 3;
const TYPE_LONG: u16 = 4;
/// Bytes per IFD entry.
const ENTRY: usize = 12;
/// The TIFF header is 8 bytes, so no IFD can start before it.
const HEADER: usize = 8;
/// BigTIFF uses a 16-byte header, 20-byte entries, and 8-byte offsets.
const BIG_ENTRY: usize = 20;
const BIG_HEADER: usize = 16;
// Keep byte-level EXIF/XMP handling in one implementation so fixes apply to all callers.
pub use craft_metadata::edit::{exif_orientation, upright_exif, upright_xmp};
/// Byte order of a TIFF structure.
#[derive(Clone, Copy)]
pub(crate) enum Order {
Little,
Big,
}
impl Order {
pub(crate) fn u16(self, b: &[u8], at: usize) -> Option<u16> {
let s: [u8; 2] = b.get(at..at.checked_add(2)?)?.try_into().ok()?;
Some(match self {
Order::Little => u16::from_le_bytes(s),
Order::Big => u16::from_be_bytes(s),
})
}
pub(crate) fn u32(self, b: &[u8], at: usize) -> Option<u32> {
let s: [u8; 4] = b.get(at..at.checked_add(4)?)?.try_into().ok()?;
Some(match self {
Order::Little => u32::from_le_bytes(s),
Order::Big => u32::from_be_bytes(s),
})
}
pub(crate) fn u64(self, b: &[u8], at: usize) -> Option<u64> {
let s: [u8; 8] = b.get(at..at.checked_add(8)?)?.try_into().ok()?;
Some(match self {
Order::Little => u64::from_le_bytes(s),
Order::Big => u64::from_be_bytes(s),
})
}
}
/// The TIFF payload of an EXIF block (a JPEG-style `Exif\0\0` prefix is skipped).
pub(crate) fn tiff_body(b: &[u8]) -> &[u8] {
b.strip_prefix(b"Exif\0\0").unwrap_or(b)
}
/// IFD0 of a TIFF structure: byte order, entry layout, and entry offsets.
///
/// The full table and next-IFD pointer must be present, and IFD0 must start
/// after the corresponding TIFF or BigTIFF header.
pub(crate) fn ifd0_entries(b: &[u8]) -> Option<(Order, usize, usize, usize, bool)> {
let (order, big_tiff) = match b.get(0..4)? {
[b'I', b'I', 42, 0] => (Order::Little, false),
[b'M', b'M', 0, 42] => (Order::Big, false),
[b'I', b'I', 43, 0] => (Order::Little, true),
[b'M', b'M', 0, 43] => (Order::Big, true),
_ => return None,
};
let (ifd, count_bytes, entry_bytes, next_ifd_bytes, header) = if big_tiff {
if order.u16(b, 4)? != 8 || order.u16(b, 6)? != 0 {
return None;
}
(usize::try_from(order.u64(b, 8)?).ok()?, 8usize, BIG_ENTRY, 8usize, BIG_HEADER)
} else {
(usize::try_from(order.u32(b, 4)?).ok()?, 2usize, ENTRY, 4usize, HEADER)
};
if ifd < header {
return None;
}
let count = if big_tiff { usize::try_from(order.u64(b, ifd)?).ok()? } else { usize::from(order.u16(b, ifd)?) };
let first = ifd.checked_add(count_bytes)?;
let next_ifd = first.checked_add(count.checked_mul(entry_bytes)?)?;
if next_ifd.checked_add(next_ifd_bytes)? > b.len() {
return None;
}
// In bounds: every entry ends at or before `next_ifd`.
Some((order, first, count, entry_bytes, big_tiff))
}
/// A well-formed Orientation entry's value: where it sits and its field type.
#[derive(Clone, Copy)]
struct Value {
at: usize,
ty: u16,
}
impl Value {
/// The stored value (a SHORT or LONG, left-justified in the 4-byte field).
fn read(self, order: Order, b: &[u8]) -> Option<u32> {
match self.ty {
TYPE_SHORT => order.u16(b, self.at).map(u32::from),
_ => order.u32(b, self.at),
}
}
/// 1 in this entry's own type, width and byte order.
fn one(self, order: Order) -> Vec<u8> {
match (self.ty, order) {
(TYPE_SHORT, Order::Little) => 1u16.to_le_bytes().to_vec(),
(TYPE_SHORT, Order::Big) => 1u16.to_be_bytes().to_vec(),
(_, Order::Little) => 1u32.to_le_bytes().to_vec(),
(_, Order::Big) => 1u32.to_be_bytes().to_vec(),
}
}
}
/// The value of the entry at `e` if it is a well-formed Orientation entry:
/// exactly one SHORT or LONG.
fn orientation_value(order: Order, b: &[u8], e: usize, big_tiff: bool) -> Option<Value> {
let count = if big_tiff { order.u64(b, e.checked_add(4)?)? } else { u64::from(order.u32(b, e.checked_add(4)?)?) };
if order.u16(b, e)? != TAG_ORIENTATION || count != 1 {
return None;
}
let ty = order.u16(b, e.checked_add(2)?)?;
let value_offset = if big_tiff { 12 } else { 8 };
matches!(ty, TYPE_SHORT | TYPE_LONG).then_some(Value { at: e.checked_add(value_offset)?, ty })
}
/// Locates the Orientation value in IFD0.
///
/// The **first** Orientation entry wins (like libexif and Photoshop); if that
/// one is malformed (count ≠ 1, or neither SHORT nor LONG) the tag is ignored,
/// even when a later duplicate is well formed.
fn find_entry(b: &[u8]) -> Option<(Order, Value)> {
let (order, first, count, entry_bytes, big_tiff) = ifd0_entries(b)?;
let e = (0..count).filter_map(|i| first.checked_add(i.checked_mul(entry_bytes)?)).find(|&e| order.u16(b, e) == Some(TAG_ORIENTATION))?;
Some((order, orientation_value(order, b, e, big_tiff)?))
}
/// The orientation (1–8) recorded in a TIFF-structured block: an EXIF payload
/// (with or without the `Exif\0\0` prefix) or a whole TIFF file. Missing,
/// malformed or out-of-range values give 1.
pub fn exif_orientation(exif: &[u8]) -> u16 {
let b = tiff_body(exif);
find_entry(b).and_then(|(order, v)| v.read(order, b)).and_then(|v| u16::try_from(v).ok()).filter(|v| (1..=8).contains(v)).unwrap_or(1)
}
/// `exif` with its Orientation rewritten to 1, borrowed when there is nothing
/// to change (no well-formed tag, already 1, or unparseable).
///
/// Only the value bytes of each well-formed Orientation entry change, written
/// as 1 in the entry's existing type and width (SHORT or LONG); every other
/// byte (other tags, their offset-based values, sub-IFDs) is kept as is.
/// Well-formed duplicates are all set to 1, so a reader that lets a later
/// duplicate win cannot rotate the upright pixels either.
pub fn upright_exif(exif: &[u8]) -> Cow<'_, [u8]> {
let body = tiff_body(exif);
let prefix = exif.len() - body.len();
let Some((order, first, count, entry_bytes, big_tiff)) = ifd0_entries(body) else {
return Cow::Borrowed(exif);
};
let values: Vec<Value> = (0..count)
.filter_map(|i| first.checked_add(i.checked_mul(entry_bytes)?))
.filter_map(|e| orientation_value(order, body, e, big_tiff))
.collect();
if values.iter().all(|v| v.read(order, body) == Some(1)) {
return Cow::Borrowed(exif);
}
let mut out = exif.to_vec();
for v in values {
let one = v.one(order);
let slot = prefix.checked_add(v.at).and_then(|at| out.get_mut(at..at.checked_add(one.len())?));
if let Some(slot) = slot {
slot.copy_from_slice(&one);
}
}
Cow::Owned(out)
}
/// `xmp` with any `tiff:Orientation` (attribute or element form) set to 1,
/// borrowed when there is nothing to change.
pub fn upright_xmp(xmp: &str) -> Cow<'_, str> {
const KEY: &str = "tiff:Orientation";
if !xmp.contains(KEY) {
return Cow::Borrowed(xmp);
}
let mut out = String::with_capacity(xmp.len());
let mut rest = xmp;
let mut changed = false;
while let Some(i) = rest.find(KEY) {
let (head, tail) = rest.split_at(i + KEY.len());
out.push_str(head);
rest = tail;
// `tiff:Orientation="6"`, `tiff:Orientation='6'` or `<tiff:Orientation>6<`.
let open = rest.char_indices().take_while(|&(_, c)| c.is_ascii_whitespace() || matches!(c, '=' | '"' | '\'' | '>')).last();
let Some((at, c)) = open else { continue };
if !matches!(c, '"' | '\'' | '>') {
continue;
}
let start = at + 1;
let digits = rest.get(start..).map_or(0, |s| s.bytes().take_while(u8::is_ascii_digit).count());
if digits == 0 || rest.get(start..start + digits) == Some("1") {
continue;
}
out.push_str(rest.get(..start).unwrap_or_default());
out.push('1');
rest = rest.get(start + digits..).unwrap_or_default();
changed = true;
}
out.push_str(rest);
if changed { Cow::Owned(out) } else { Cow::Borrowed(xmp) }
/// TIFF payload of an EXIF block (a JPEG-style `Exif\0\0` prefix is skipped).
pub(crate) fn tiff_body(bytes: &[u8]) -> &[u8] {
bytes.strip_prefix(b"Exif\0\0").unwrap_or(bytes)
}
/// Source pixel index for output pixel `(0, y2)` and the step per output column, for
+190
View File
@@ -0,0 +1,190 @@
//! Header-only PNG inspection without inflating image data.
use crate::{CodecError, Format};
fn err(message: &str) -> CodecError {
CodecError::malformed(Format::Png, message)
}
/// Dimensions declared in a PNG IHDR prefix, without checking the rest of the file.
/// Useful only for an early allocation limit; use [`header`] for structural inspection.
pub fn declared_dimensions(b: &[u8]) -> Option<(u32, u32)> {
if !b.starts_with(b"\x89PNG\r\n\x1a\n") || b.get(12..16) != Some(b"IHDR") {
return None;
}
let w = u32::from_be_bytes(b.get(16..20)?.try_into().ok()?);
let h = u32::from_be_bytes(b.get(20..24)?.try_into().ok()?);
Some((w, h))
}
/// Stored dimensions and EXIF orientation. This does not validate CRCs or compressed pixels.
pub fn header(b: &[u8]) -> Result<(u32, u32, u16), CodecError> {
header_with_max_pixels(b, u64::MAX)
}
/// As [`header`], refusing images over `max_pixels` before scanning their chunks.
pub fn header_with_max_pixels(b: &[u8], max_pixels: u64) -> Result<(u32, u32, u16), CodecError> {
if !b.starts_with(b"\x89PNG\r\n\x1a\n") {
return Err(err("bad signature"));
}
let be32 = |p: usize| b.get(p..p.checked_add(4)?).map(|v| u32::from_be_bytes([v[0], v[1], v[2], v[3]]));
if be32(8) != Some(13) || b.get(12..16) != Some(b"IHDR") {
return Err(err("missing IHDR"));
}
let ihdr = b.get(16..29).ok_or_else(|| err("truncated IHDR"))?;
let (w, h) = (u32::from_be_bytes([ihdr[0], ihdr[1], ihdr[2], ihdr[3]]), u32::from_be_bytes([ihdr[4], ihdr[5], ihdr[6], ihdr[7]]));
let (depth, color, compression, filter, interlace) = (ihdr[8], ihdr[9], ihdr[10], ihdr[11], ihdr[12]);
if w > i32::MAX as u32 || h > i32::MAX as u32 {
return Err(err("dimensions out of range"));
}
if w == 0 || h == 0 {
return Err(err("zero dimension"));
}
if u64::from(w) * u64::from(h) > max_pixels {
return Err(CodecError::LimitExceeded("PNG pixel count".into()));
}
let depth_ok = match color {
0 => matches!(depth, 1 | 2 | 4 | 8 | 16),
3 => matches!(depth, 1 | 2 | 4 | 8),
2 | 4 | 6 => matches!(depth, 8 | 16),
_ => false,
};
if !depth_ok || compression != 0 || filter != 0 || interlace > 1 {
return Err(err("invalid IHDR"));
}
let (mut p, mut palette, mut idat, mut after_idat, mut exif) = (8usize, false, false, false, None);
while let Some(len) = be32(p) {
let Some(kind) = p.checked_add(4).and_then(|k| b.get(k..k.checked_add(4)?)) else { break };
if idat && kind != b"IDAT" {
// a chunk follows the image data: the IDAT run is complete
after_idat = true;
}
if kind == b"IEND" {
break;
}
let start = p.saturating_add(8);
let data = (len <= i32::MAX as u32).then(|| start.checked_add(len as usize).and_then(|end| b.get(start..end))).flatten();
let Some(data) = data else {
if after_idat {
break; // a damaged chunk after the image data: a decode ignores it too
}
return Err(err("truncated"));
};
match kind {
b"PLTE" => palette = true,
b"IDAT" if after_idat => {} // a stray IDAT after other chunks: the first run is the image
b"IDAT" => {
if color == 3 && !palette {
return Err(err("indexed image without a palette"));
}
idat = true;
}
b"eXIf" if exif.is_none() => exif = Some(data.strip_prefix(b"Exif\0\0").unwrap_or(data)),
_ => {}
}
p = start.saturating_add(data.len()).saturating_add(4);
}
if !idat {
return Err(err("no image data"));
}
if !after_idat {
return Err(err("truncated image data"));
}
Ok((w, h, exif.map_or(1, crate::exif_orientation)))
}
/// Container color declarations preceding image data. Raw values leave color policy to callers.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct ColorChunks {
pub srgb: bool,
pub gamma: Option<f32>,
pub chromaticities: Option<[f64; 8]>,
}
/// Read bounded color chunks before image data; malformed tails are ignored.
pub fn color_chunks(b: &[u8]) -> Option<ColorChunks> {
if !b.starts_with(b"\x89PNG\r\n\x1a\n") {
return None;
}
let mut result = ColorChunks::default();
let mut p = 8usize;
while let Some(length) = b.get(p..p.checked_add(4)?) {
let len = u32::from_be_bytes(length.try_into().ok()?) as usize;
let start = p.checked_add(8)?;
let Some(kind) = b.get(p.checked_add(4)?..start) else { break };
let Some(payload) = start.checked_add(len).and_then(|end| b.get(start..end)) else { break };
match kind {
b"sRGB" => result.srgb = true,
b"gAMA" if payload.len() == 4 => {
let v = u32::from_be_bytes(payload.try_into().ok()?) as f32 / 100_000.0;
if v > 0.0 && v.is_finite() {
result.gamma = Some(v);
}
}
b"cHRM" if payload.len() == 32 => {
let mut vals = [0.0; 8];
for (i, dst) in vals.iter_mut().enumerate() {
let raw = i32::from_be_bytes(payload[i * 4..i * 4 + 4].try_into().ok()?);
*dst = f64::from(raw) / 100_000.0;
}
result.chromaticities = Some(vals);
}
b"IDAT" | b"IEND" => break,
_ => {}
}
let Some(next) = start.checked_add(len).and_then(|end| end.checked_add(4)) else { break };
p = next;
}
Some(result)
}
#[cfg(test)]
mod tests {
use super::*;
fn chunk(out: &mut Vec<u8>, kind: &[u8; 4], data: &[u8]) {
out.extend_from_slice(&(data.len() as u32).to_be_bytes());
out.extend_from_slice(kind);
out.extend_from_slice(data);
out.extend_from_slice(&[0; 4]); // Header inspection deliberately does not validate CRCs.
}
fn png(color: u8) -> Vec<u8> {
let mut bytes = b"\x89PNG\r\n\x1a\n".to_vec();
let mut ihdr = Vec::new();
ihdr.extend_from_slice(&2u32.to_be_bytes());
ihdr.extend_from_slice(&3u32.to_be_bytes());
ihdr.extend_from_slice(&[8, color, 0, 0, 0]);
chunk(&mut bytes, b"IHDR", &ihdr);
bytes
}
#[test]
fn header_checks_structure_and_reads_late_orientation_without_crc_validation() {
let mut bytes = png(2);
chunk(&mut bytes, b"IDAT", &[1]);
let exif = b"II\x2a\x00\x08\x00\x00\x00\x01\x00\x12\x01\x03\x00\x01\x00\x00\x00\x06\x00\x00\x00\x00\x00\x00\x00";
chunk(&mut bytes, b"eXIf", exif);
chunk(&mut bytes, b"IEND", &[]);
assert_eq!(header(&bytes).ok(), Some((2, 3, 6)));
assert!(matches!(header_with_max_pixels(&bytes, 5), Err(CodecError::LimitExceeded(_))));
assert_eq!(declared_dimensions(&bytes), Some((2, 3)));
assert!(header(&bytes[..34]).is_err());
let mut indexed = png(3);
chunk(&mut indexed, b"IDAT", &[1]);
chunk(&mut indexed, b"IEND", &[]);
assert!(header(&indexed).is_err());
indexed[25] = 7;
assert!(header(&indexed).is_err());
}
#[test]
fn reads_color_chunks_only_before_image_data() {
let mut bytes = png(2);
chunk(&mut bytes, b"gAMA", &45455u32.to_be_bytes());
chunk(&mut bytes, b"IDAT", &[1]);
chunk(&mut bytes, b"sRGB", &[0]);
let color = color_chunks(&bytes).unwrap();
assert_eq!(color.gamma, Some(0.45455));
assert!(!color.srgb);
assert!(color_chunks(b"not png").is_none());
}
}
@@ -62,6 +62,7 @@ fn default_build_formats_all_symmetric() {
Format::Dpx,
Format::Cineon,
Format::Iff,
Format::JpegLs,
];
for f in expected {
assert!(caps(f).read && caps(f).write, "{f:?}");
@@ -223,6 +224,21 @@ fn detect_magic_iff() {
assert_eq!(detect(b"FORM\0\0\0\x14AIFF"), None);
assert!(decode_as(Format::Iff, b"FORM\0\0\0\x14ILBM").is_err());
}
#[test]
fn detect_magic_jpeg_ls() {
use craft_image_codecs::{ChannelLayout, EncodeOptions, Image, encode};
let img = Image::from_u8(5, 3, ChannelLayout::Gray, (0..15).collect()).unwrap();
let bytes = encode(&img, Format::JpegLs, &EncodeOptions::default()).unwrap();
assert_eq!(detect(&bytes), Some(Format::JpegLs));
assert_eq!(from_extension("scan.JLS"), Some(Format::JpegLs));
assert_eq!(decode(&bytes).unwrap().data(), img.data());
assert!(!ASYMMETRIC_EXCEPTIONS.iter().any(|(f, _)| *f == Format::JpegLs));
assert_eq!(Format::JpegLs.max_dimensions(), Some((65535, 65535)));
// Plain JPEG still is JPEG: SOI, then a baseline frame header.
assert_eq!(detect(&[0xFF, 0xD8, 0xFF, 0xC0, 0, 11]), Some(Format::Jpeg));
assert!(decode_as(Format::JpegLs, &[0xFF, 0xD8, 0xFF, 0xF7]).is_err());
}
#[test]
fn detect_magic_avif() {
assert_eq!(detect(b"\0\0\0\x1cftypavif\0\0\0\0avifmif1miaf"), Some(Format::Avif));
@@ -0,0 +1,103 @@
//! JPEG-LS against ffmpeg as the reference (oracle; skipped when ffmpeg is absent, a failure with
//! `CRAFT_MEDIA_REQUIRE_ORACLES=1`):
//! - files ffmpeg's encoder writes (8- and 16-bit gray: smooth, noisy and flat images, which
//! exercise the regular, run and escape-coded paths) decode to the pixels ffmpeg decodes;
//! - files our encoder writes (gray 8 and 16 bits, RGB 8 bits) decode in ffmpeg to our pixels (ffmpeg
//! cannot decode 16-bit RGB JPEG-LS, so that case is only round-tripped through our own decoder);
//! - ffmpeg writes RGB line-interleaved, which is reported as unsupported.
use craft_image_codecs::{ChannelLayout, CodecError, EncodeOptions, Format, Image, SampleType, decode, encode};
use std::path::Path;
use std::process::Command;
const W: u32 = 66;
const H: u32 = 40;
fn run(ffmpeg: &Path, args: &[&str]) -> Vec<u8> {
let out = Command::new(ffmpeg).args(["-v", "error", "-y"]).args(args).output().expect("run ffmpeg");
assert!(out.status.success(), "ffmpeg {args:?}: {}", String::from_utf8_lossy(&out.stderr));
out.stdout
}
/// `(name, lavfi source)`: smooth, noisy and flat pictures of W x H.
fn sources() -> Vec<(&'static str, String)> {
let s = format!("{W}x{H}");
vec![
("testsrc", format!("testsrc2=size={s}:rate=1")),
("noise", format!("nullsrc=size={s}:rate=1,geq=lum='random(1)*255':cb=128:cr=128")),
("flat", format!("color=c=0x336699:size={s}:rate=1")),
("gradient", format!("gradients=size={s}:rate=1:seed=7")),
]
}
#[test]
fn ffmpeg_files_decode_to_ffmpegs_pixels() {
let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("jpegls");
for (name, src) in sources() {
for (fmt, ext_bits) in [("gray", 8), ("gray16le", 16)] {
let file = dir.join(format!("ffmpeg_{name}_{ext_bits}.jls"));
let f = file.to_str().expect("path");
run(&ffmpeg, &["-f", "lavfi", "-i", &src, "-frames:v", "1", "-pix_fmt", fmt, f]);
let theirs = run(&ffmpeg, &["-i", f, "-f", "rawvideo", "-pix_fmt", fmt, "-"]);
let ours = decode(&std::fs::read(&file).expect("read")).unwrap_or_else(|e| panic!("{name} {fmt}: {e}"));
assert_eq!((ours.width(), ours.height(), ours.layout()), (W, H, ChannelLayout::Gray), "{name} {fmt}");
let want_sample = if ext_bits == 8 { SampleType::U8 } else { SampleType::U16 };
assert_eq!(ours.sample_type(), want_sample);
let ours_bytes: Vec<u8> = if ext_bits == 8 {
ours.data().to_vec()
} else {
ours.data().as_chunks::<2>().0.iter().flat_map(|b| u16::from_ne_bytes(*b).to_le_bytes()).collect()
};
assert!(ours_bytes == theirs, "{name} {fmt}: pixels differ from ffmpeg's decode");
}
}
}
#[test]
fn ffmpegs_rgb_is_line_interleaved_and_unsupported() {
let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("jpegls");
let file = dir.join("ffmpeg_rgb.jls");
run(
&ffmpeg,
&["-f", "lavfi", "-i", &format!("testsrc2=size={W}x{H}:rate=1"), "-frames:v", "1", "-pix_fmt", "rgb24", file.to_str().expect("path")],
);
assert!(matches!(decode(&std::fs::read(&file).expect("read")), Err(CodecError::Unsupported { .. })));
}
#[test]
fn ffmpeg_decodes_our_files_to_our_pixels() {
let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("jpegls");
for (name, src) in sources() {
for (layout, fmt8, fmt16) in [(ChannelLayout::Gray, "gray", "gray16le"), (ChannelLayout::Rgb, "rgb24", "rgb48le")] {
for bits in [8, 16] {
let fmt = if bits == 8 { fmt8 } else { fmt16 };
// Source pixels from ffmpeg, so the test image is realistic.
let raw = run(&ffmpeg, &["-f", "lavfi", "-i", &src, "-frames:v", "1", "-pix_fmt", fmt, "-f", "rawvideo", "-"]);
let img = if bits == 8 {
Image::from_u8(W, H, layout, raw).expect("image")
} else {
let samples: Vec<u16> = raw.as_chunks::<2>().0.iter().map(|b| u16::from_le_bytes(*b)).collect();
Image::from_u16(W, H, layout, &samples).expect("image")
};
let bytes = encode(&img, Format::JpegLs, &EncodeOptions::default()).expect("encode");
assert_eq!(decode(&bytes).expect("our own file decodes").data(), img.data(), "{name} {fmt}: round trip");
let file = dir.join(format!("ours_{name}_{fmt}.jls"));
std::fs::write(&file, &bytes).expect("write");
// ffmpeg's decoder does not implement 16-bit colour ("Not yet implemented").
if layout == ChannelLayout::Rgb && bits == 16 {
continue;
}
let theirs = run(&ffmpeg, &["-i", file.to_str().expect("path"), "-f", "rawvideo", "-pix_fmt", fmt, "-"]);
let ours_bytes: Vec<u8> = if bits == 8 {
img.data().to_vec()
} else {
img.data().as_chunks::<2>().0.iter().flat_map(|b| u16::from_ne_bytes(*b).to_le_bytes()).collect()
};
assert!(theirs == ours_bytes, "{name} {fmt}: ffmpeg decodes our file to other pixels");
}
}
}
}
+1
View File
@@ -14,6 +14,7 @@ mod exr_stream;
mod fidelity;
mod gif_frames;
mod heif;
mod jpegls_oracle;
mod limits;
mod malformed;
mod metadata;
+94
View File
@@ -665,3 +665,97 @@ fn step_stream_gives_the_pixels_and_extras_of_decode() {
fn dec_line(w: u32, layout: ChannelLayout, sample: SampleType) -> usize {
w as usize * layout.channels() * sample.bytes()
}
#[test]
fn bounded_png_stream_does_not_charge_unretained_full_frame() {
let image = synth(256, 1024, ChannelLayout::Rgba, SampleType::U16, 77, 0.5);
let bytes = encode(&image, Format::Png, &EncodeOptions::default()).unwrap();
let limits = Limits { max_alloc: 512 * 1024, ..Limits::default() };
assert!(image.data().len() > limits.max_alloc as usize);
assert!(PngDecodeRows::new(bytes.as_slice(), &limits).is_err());
assert!(PngDecodeRows::new_streaming(bytes.as_slice(), &limits).is_err());
let mut decoder = PngDecodeRows::new_bounded_streaming(bytes.as_slice(), &limits).unwrap();
assert!(decoder.streamable());
// Opening a stream must not become a way to bypass whole-image allocation guards.
assert!(decoder.reserve_output().is_err());
assert!(decoder.step(&mut || true).is_err());
let mut next = 0;
let mut sink = |first: u32, rows: &[u8]| -> Result<(), CodecError> {
assert_eq!(first as usize, next);
assert!(rows.len() <= 3 * 256 * 8);
let start = next * 256 * 8;
assert_eq!(rows, &image.data()[start..start + rows.len()]);
next += rows.len() / (256 * 8);
Ok(())
};
while decoder.step_stream(3, &mut || false, &mut sink).unwrap().is_none() {}
assert_eq!(next, 1024);
}
#[test]
fn bounded_png_stream_keeps_group_dimension_and_fallback_limits() {
let image = synth(256, 1024, ChannelLayout::Rgba, SampleType::U16, 81, 0.5);
let bytes = encode(&image, Format::Png, &EncodeOptions::default()).unwrap();
let limits = Limits { max_alloc: 512 * 1024, ..Limits::default() };
let mut decoder = PngDecodeRows::new_bounded_streaming(bytes.as_slice(), &limits).unwrap();
assert!(decoder.step_stream::<CodecError>(1024, &mut || true, &mut |_, _| panic!("oversized group reached sink")).is_err());
for strict in [
Limits { max_width: 255, ..limits },
Limits { max_height: 1023, ..limits },
Limits { max_pixels: 256 * 1024 - 1, ..limits },
Limits { max_alloc: 1024, ..limits },
] {
assert!(PngDecodeRows::new_bounded_streaming(bytes.as_slice(), &strict).is_err());
}
let adam7 = interlaced(&image);
assert!(PngDecodeRows::new_bounded_streaming(adam7.as_slice(), &limits).is_err());
}
#[test]
fn bounded_png_stream_rejects_shrinking_below_buffered_rows() {
let image = synth(16, 8, ChannelLayout::Rgba, SampleType::U16, 83, 0.5);
let bytes = encode(&image, Format::Png, &EncodeOptions::default()).unwrap();
let mut decoder = PngDecodeRows::new_bounded_streaming(bytes.as_slice(), &Limits::default()).unwrap();
for _ in 0..3 {
assert!(decoder.step_stream::<CodecError>(4, &mut || false, &mut |_, _| panic!("group is incomplete")).unwrap().is_none());
}
assert!(decoder.step_stream::<CodecError>(1, &mut || true, &mut |_, _| panic!("changed group reached sink")).is_err());
let mut output = Vec::new();
decoder
.step_stream::<CodecError>(4, &mut || true, &mut |_, rows| {
output.extend_from_slice(rows);
Ok(())
})
.unwrap();
assert_eq!(output, image.data());
}
#[test]
fn bounded_png_stream_preserves_late_exif_across_metadata_yields() {
let image = synth(16, 8, ChannelLayout::Rgba, SampleType::U16, 89, 0.5);
let bytes = encode(&image, Format::Png, &EncodeOptions::default()).unwrap();
let mut exif = sample_exif();
exif[18..22].copy_from_slice(&6u32.to_le_bytes());
let mut chunks = vec![png_chunk(b"eXIf", &exif)];
for i in 0..150 {
chunks.push(png_chunk(b"tEXt", format!("key{i}\0value").as_bytes()));
}
let bytes = with_chunks_before_iend(&bytes, &chunks);
let mut decoder = PngDecodeRows::new_bounded_streaming(bytes.as_slice(), &Limits::default()).unwrap();
assert!(decoder.streamable());
let mut output = Vec::new();
let extras = loop {
if let Some(extras) = decoder
.step_stream::<CodecError>(2, &mut || false, &mut |_, rows| {
output.extend_from_slice(rows);
Ok(())
})
.unwrap()
{
break extras;
}
};
assert_eq!(output, image.data());
assert_eq!(extras.orientation, 6);
assert_eq!(extras.meta.text.len(), 150);
}
+58
View File
@@ -195,3 +195,61 @@ where
let responses: Vec<_> = batch.iter().filter_map(|v| one(v, limits, &mut on_request, &mut on_notification)).collect();
Ok((!responses.is_empty()).then_some(Value::Array(responses)))
}
/// Process a permissive legacy JSON-RPC envelope. This mode accepts arbitrary IDs and
/// parameter shapes, ignores response envelopes, and retains legacy diagnostic messages.
/// The caller supplies dispatch and notification callbacks, and should bound transport input.
pub fn process_legacy<F, N>(value: &Value, mut on_request: F, mut on_notification: N) -> Option<Value>
where
F: FnMut(Request<'_>) -> Result<Value, RpcError>,
N: FnMut(Request<'_>),
{
fn one<F, N>(value: &Value, on_request: &mut F, on_notification: &mut N) -> Option<Value>
where
F: FnMut(Request<'_>) -> Result<Value, RpcError>,
N: FnMut(Request<'_>),
{
let Some(object) = value.as_object() else { return Some(error_response(Value::Null, RpcError::new(-32600, "message must be an object"))) };
let id = object.get("id");
let Some(method) = object.get("method").and_then(Value::as_str) else {
if object.contains_key("result") || object.contains_key("error") {
return None;
}
return Some(error_response(id.cloned().unwrap_or(Value::Null), RpcError::new(-32600, "missing `method`")));
};
let request = Request { id, method, params: object.get("params") };
let Some(id) = id else {
on_notification(request);
return None;
};
Some(match on_request(request) {
Ok(result) => json!({"jsonrpc": "2.0", "id": id, "result": result}),
Err(error) => error_response(id.clone(), error),
})
}
if let Some(batch) = value.as_array() {
if batch.is_empty() {
return Some(error_response(Value::Null, RpcError::new(-32600, "empty batch")));
}
let replies: Vec<_> = batch.iter().filter_map(|v| one(v, &mut on_request, &mut on_notification)).collect();
(!replies.is_empty()).then_some(Value::Array(replies))
} else {
one(value, &mut on_request, &mut on_notification)
}
}
#[cfg(test)]
mod legacy_tests {
use super::*;
#[test]
fn preserves_legacy_batch_routing_and_errors() {
let input = json!([{"id": [1], "method":"echo", "params":5}, {"method":"notice"}, {"result":1}, {}, 7]);
let seen = std::cell::Cell::new(false);
let result = process_legacy(&input, |r| Ok(r.params.cloned().unwrap_or(Value::Null)), |_| seen.set(true)).unwrap();
assert!(seen.get());
assert_eq!(
result,
json!([{"jsonrpc":"2.0","id":[1],"result":5}, {"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"missing `method`"}}, {"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"message must be an object"}}])
);
assert_eq!(process_legacy(&json!([]), |_| Ok(Value::Null), |_| {}).unwrap()["error"]["message"], "empty batch");
}
}

Some files were not shown because too many files have changed in this diff Show More