1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
use clap::{ArgAction, Parser, Subcommand, ValueEnum};
/// EXIF metadata policy values of the `--exif` flag.
#[derive(Clone, Copy, Debug, PartialEq, Eq, ValueEnum)]
pub enum ExifPolicyArg {
/// Copy EXIF verbatim into outputs that support it.
Keep,
/// Remove all EXIF from outputs (default).
Strip,
/// Keep all but `--exif-except <TAGS>`, or only `--exif-only <TAGS>`.
Filter,
}
/// Behavior when animated input meets a target that cannot encode animations.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, ValueEnum)]
pub enum AnimatedInputArg {
/// Encode the first frame only, printing a notice (default).
#[default]
FirstFrame,
/// Fail the file with an error instead of silently dropping animation.
Error,
}
/// Image converter CLI
#[derive(Parser, Debug)]
#[command(
version,
about,
long_about = None
)]
pub struct CliArgs {
/// The command to execute.
#[command(subcommand)]
pub command: Command,
/// Glob pattern to match images to convert.
/// Example: `images/**/*.png`
//#[clap(global = true)]
// arguments can't be global and required
// => early exit for no pattern matches
pub pattern: String,
/// Output directory (flat) of processed images.
/// Defaults to the same location as the original images with the new file extension.
/// If set, replaces the fixed base of the pattern directory structure of the input pattern. (before any * in the glob pattern)
#[clap(short, long, global = true, default_value = None)]
pub output: Option<String>,
/// By default, byteshaver will process input files in lexicographical order after expanding the pattern.
/// Setting this starts the process from the back.
#[clap(long, global = true, action = Some(ArgAction::SetTrue))]
pub reverse_processing_order: Option<bool>,
/// Overwrite the existing output file if the current conversion resulted in a smaller file.
#[clap(long, global = true, action = Some(ArgAction::SetTrue))]
pub overwrite_if_smaller: Option<bool>,
/// Overwrite existing output files regardless of size.
#[clap(long, global = true, action = Some(ArgAction::SetTrue))]
pub overwrite_existing: Option<bool>,
/// Discards the encoding result if it is larger than the input file (does not create an output file).
#[clap(long, global = true, action = Some(ArgAction::SetTrue))]
pub discard_if_larger_than_input: Option<bool>,
/// Discards the alpha channel of the input image(s) if it is present.
/// (this does not make loading faster, but it can improve the encoding result)
#[clap(long, global = true, action = Some(ArgAction::SetTrue))]
pub discard_input_alpha_channel: Option<bool>,
/// EXIF metadata handling policy (global).
/// strip: remove all EXIF and bake the orientation into the pixels (default, privacy-safe).
/// keep: copy EXIF verbatim into outputs where the container supports it.
/// filter: keep all tags except --exif-except <TAGS>, or only --exif-only <TAGS>.
#[clap(long, value_enum, value_name = "keep|strip|filter", global = true)]
pub exif: Option<ExifPolicyArg>,
/// Comma-separated EXIF tags/IFDs to drop when using --exif filter
/// (e.g. --exif-except gps,GPSInfo,Orientation; names from --exif-list-tags,
/// IFD wildcards ifd0/ifd1/exif/gps/interop, or numeric tags like 0x8825).
/// Mutually exclusive with --exif-only; requires --exif filter.
#[clap(
long,
value_delimiter = ',',
value_name = "TAGS",
global = true,
requires = "exif"
)]
pub exif_except: Option<Vec<String>>,
/// Comma-separated EXIF tags/IFDs to keep when using --exif filter
/// (same syntax as --exif-except).
/// Mutually exclusive with --exif-except; requires --exif filter.
#[clap(
long,
value_delimiter = ',',
value_name = "TAGS",
global = true,
conflicts_with = "exif_except",
requires = "exif"
)]
pub exif_only: Option<Vec<String>>,
/// Print recognized EXIF tag names and exit.
#[clap(long, action = Some(ArgAction::SetTrue))]
pub exif_list_tags: Option<bool>,
/// How to treat HEIC/HEIF files containing more than one image
/// (requires a build with the `dec-heif` feature):
/// primary: decode only the primary image (default).
/// all: decode every image; outputs are named stem.ext, stem_1.ext, ...
#[cfg(all(feature = "dec-heif", any(not(target_os = "windows"), target_abi = "llvm")))]
#[clap(long, value_enum, value_name = "primary|all", global = true)]
pub heif_image_policy: Option<crate::config::HeifImagePolicy>,
/// How to treat animated input (gif / animated webp / APNG) when the
/// selected target cannot encode animations.
/// first-frame: encode the first frame only, with a notice (default).
/// error: fail the file with an error instead of silently dropping
/// the animation (for pipelines that must never drop frames).
#[clap(long, value_enum, value_name = "first-frame|error", global = true)]
pub animated_input: Option<AnimatedInputArg>,
/// Hard cap for decoded animation memory in MiB (frames are RGBA:
/// width x height x 4 x frames). Files whose projected frame buffers
/// exceed the cap fail with an error instead of risking an OOM.
/// Defaults to 4096.
#[clap(long, value_name = "MIB", global = true)]
pub max_animation_memory: Option<u64>,
/// Write one JSON object per progress event to this file (JSON lines)
/// in addition to the regular stdout output (requires the `logs`
/// feature, on by default).
#[cfg(feature = "logs")]
#[clap(long, global = true, value_name = "PATH")]
pub json_log: Option<std::path::PathBuf>,
}
/// Image converter actions
#[derive(Subcommand, Debug)]
pub enum Command {
/// Convert images to webp format (using webp crate)
Webp {
/// Use lossless encoding mode. Defaults to false.
#[clap(long, action = Some(ArgAction::SetTrue))]
lossless: Option<bool>,
/// Control target quality (0 - 100, lower is worse but results in smaller files).
/// Defaults to 90.0.
#[clap(short, long)]
quality: Option<f32>,
},
/// Convert images to webp format (using image crate)
WebpImage {}, // only lossless is available, no configuration parameters
/// Convert images to avif format (using ravif crate)
Avif {
/// Control target quality (0 - 100, lower is worse but results in smaller files).
/// Defaults to 90.0.
#[clap(short, long)]
quality: Option<f32>,
/// Control encoding speed (1 - 10, lower is much slower but has a better quality and lower filesize).
/// Defaults to 3.
#[clap(short, long)]
speed: Option<u8>,
/// Choose internal bit depth. (in the generated avif file, nothing to do with the input file)
#[clap(long, value_enum)]
bit_depth: Option<crate::config::BitDepth>,
/// Choose internal color model. (in the generated avif file, nothing to do with the input file)
#[clap(long, value_enum)]
color_model: Option<crate::config::ColorModel>,
/// Choose internal alpha color mode. (in the generated avif file, nothing to do with the input file)
/// Irrelevant for images without transparency.
#[clap(long, value_enum)]
alpha_color_mode: Option<crate::config::AlphaColorMode>,
/// Control target alpha quality (0 - 100, lower is worse).
/// Defaults to 90.0.
#[clap(short, long)]
alpha_quality: Option<f32>,
},
/// Convert images to png format (using image crate)
Png {
/// Choose the png compression type
///
/// See: https://docs.rs/image/latest/image/codecs/png/enum.CompressionType.html
#[clap(long, value_enum)]
compression_type: Option<crate::config::CompressionType>,
/// Choose the png filter type
///
/// See: https://docs.rs/image/latest/image/codecs/png/enum.CompressionType.html
#[clap(long, value_enum)]
filter_type: Option<crate::config::FilterType>,
},
/// Convert images to optimized jpeg format (using mozjpeg crate)
Jpeg {},
/// Convert images to jpeg-xl format (using libjxl)
#[cfg(feature = "jxl")]
Jxl {
/// JPEG-style quality 0-100 (higher = better). Mutually exclusive with --distance.
#[clap(short, long, group = "jxl-quality-group")]
quality: Option<f32>,
/// Maximum Butteraugli distance 0.0-25.0 (0.0 = mathematically lossless,
/// 1.0 = visually lossless, libjxl default 1.0). Mutually exclusive with --quality.
#[clap(long, group = "jxl-quality-group")]
distance: Option<f32>,
/// Lossless mode. Overrides quality/distance.
#[clap(long, action = Some(ArgAction::SetTrue))]
lossless: Option<bool>,
/// Encoding effort 1 (fastest) - 10 (slowest/best). Defaults to 7.
#[clap(short, long, value_parser = clap::value_parser!(u8).range(1..=10))]
effort: Option<u8>,
/// Force the box-based container format (required for manual Exif/XMP embedding;
/// auto-enabled when EXIF is embedded).
#[clap(long, action = Some(ArgAction::SetTrue))]
container: Option<bool>,
/// Keep the original color profile (do not convert to internal XYB); needed for lossless.
#[clap(long, action = Some(ArgAction::SetTrue))]
original_profile: Option<bool>,
/// Target decode speed tier 0-4 (higher = faster decode, larger file). Defaults to 0.
#[clap(long, value_parser = clap::value_parser!(u8).range(0..=4))]
decoding_speed: Option<u8>,
/// Photometric target intensity in nits (HDR). Defaults to libjxl's 255.
#[clap(long)]
intensity_target: Option<f32>,
/// Force output bit depth: 8 or 16 (default: follow the input).
#[clap(long, value_parser = clap::value_parser!(u8).range(8..=16))]
bit_depth: Option<u8>,
/// Color encoding: srgb | linear-srgb | srgb-luma | linear-srgb-luma | icc-passthrough.
/// Defaults to srgb.
#[clap(long, value_enum)]
color_encoding: Option<crate::config::JxlColorEncodingChoice>,
/// Advanced: repeatable libjxl frame-setting passthrough, e.g. --setting brotli_effort=9
/// (ids are resolved case-insensitively; unknown ids list the available set).
#[clap(long = "setting", value_name = "ID=VALUE")]
settings: Vec<String>,
},
/// Convert images to optimally compressed png format (using oxipng)
#[cfg(feature = "opt-oxipng")]
Oxipng {
/// Optimization level 0-6 (preset), or `max`. Default 2. Higher = slower.
///
/// Explicit flags are applied on top of the chosen preset
/// (preset first, explicit overrides second).
#[clap(short, long, value_enum)]
level: Option<crate::config::OxipngLevel>,
/// Use zopfli DEFLATE instead of libdeflate (much slower, slightly smaller).
#[clap(long, action = Some(ArgAction::SetTrue))]
zopfli: Option<bool>,
/// zopfli iteration count when --zopfli is set. Defaults to 15.
#[clap(long)]
zopfli_iterations: Option<u32>,
/// Interlacing handling: keep | none | adam7.
/// Defaults to none (oxipng default removes interlacing).
#[clap(long, value_enum)]
interlace: Option<crate::config::OxipngInterlace>,
/// Metadata stripping: none | safe | all. Defaults to none.
#[clap(long, value_enum)]
strip: Option<crate::config::OxipngStrip>,
/// Filter strategies to try (repeatable, comma-separated):
/// none, sub, up, avg, paeth, minsum, entropy, bigrams, bigent, brute.
/// Replaces the filter set of the chosen level preset.
#[clap(long, value_enum, value_delimiter = ',')]
filters: Vec<crate::config::OxipngFilter>,
/// Allow altering transparent pixel values for better compression (lossless visually).
#[clap(long, action = Some(ArgAction::SetTrue))]
optimize_alpha: Option<bool>,
/// Disable lossless reductions (repeatable, comma-separated):
/// bit-depth, color-type, palette, grayscale.
#[clap(long, value_enum, value_delimiter = ',')]
no_reduction: Vec<crate::config::OxipngReduction>,
/// Force 16-bit to 8-bit scaling when losslessly possible.
#[clap(long, action = Some(ArgAction::SetTrue))]
scale_16: Option<bool>,
/// Attempt fixing broken input pngs instead of erroring.
#[clap(long, action = Some(ArgAction::SetTrue))]
fix_errors: Option<bool>,
/// Stop optimizing a file after this many seconds. Default: unlimited.
#[clap(long, value_name = "SECS")]
timeout_secs: Option<u64>,
},
/// Convert images to animated webp format (using webp-animation crate).
/// Supports animated input (gif, animated webp, APNG); the source loop
/// count is preserved. Still input becomes a 1-frame animation.
#[cfg(feature = "anim-webp")]
WebpAnim {
/// Use lossless encoding mode. Defaults to false.
#[clap(long, action = Some(ArgAction::SetTrue))]
lossless: Option<bool>,
/// Control target quality (0 - 100, lower is worse but results in smaller files).
/// In lossless mode this is the compression effort. Defaults to 90.0.
#[clap(short, long)]
quality: Option<f32>,
/// Minimum distance between keyframes (0 = libwebp default).
#[clap(long)]
kmin: Option<i32>,
/// Maximum distance between keyframes (0 = disables keyframe insertion).
#[clap(long)]
kmax: Option<i32>,
/// Minimize the output size (much slower; disables keyframe insertion).
#[clap(long, action = Some(ArgAction::SetTrue))]
minimize_size: Option<bool>,
/// Allow mixed lossy/lossless frames (libwebp picks per frame).
#[clap(long, action = Some(ArgAction::SetTrue))]
allow_mixed: Option<bool>,
/// Quality/speed trade-off (0 = fast, 6 = slower-better). Defaults to 4.
#[clap(long)]
method: Option<u8>,
},
/// Convert images to animated png format (APNG, using png crate).
/// Supports animated input (gif, animated webp, APNG); the source loop
/// count is preserved. Still input becomes a 1-frame animation.
/// The default image stays readable by non-APNG-aware viewers.
#[cfg(feature = "anim-apng")]
Apng {
/// Choose the png compression type (Fast pairs well with a
/// following oxipng post-optimization pass)
///
/// See: https://docs.rs/image/latest/image/codecs/png/enum.CompressionType.html
#[clap(long, value_enum)]
compression_type: Option<crate::config::CompressionType>,
/// Choose the png filter type
///
/// See: https://docs.rs/image/latest/image/codecs/png/enum.CompressionType.html
#[clap(long, value_enum)]
filter_type: Option<crate::config::FilterType>,
},
/// Convert images to (animated) gif format (using image crate).
/// Supports animated input; the source loop count is preserved.
/// Note: frame delays are rounded to the GIF-standard 10 ms granularity.
Gif {
/// Quantization speed (1 = best quality, 30 = fastest). Defaults to 10.
#[clap(long)]
speed: Option<i32>,
},
/// Remove files matching a glob pattern
Clean {},
}