feat: Additional options for saveArtwork (#9)

- New `format` option which allows us to specify the format of the saved file (defaults to `jpeg`).
- Changed `compress` option to expect a number between `0.0` & `1.0` which represents the quality of the saved image (defaults to `1`).

Author: cyanChill

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+### ❗ Breaking Changes
+
+- Revised "compression" option for `saveArtwork`.
+- Changed `ArtworkOptions` type.
+  - `compress` is now a number between `0.0` & `1.0` specifying the quality of the saved image (defaults to `1`).
+  - New `format` option specifying the file format the image will be saved as (defaults to `jpeg`).
+
 ## [2.0.0-beta.1] - 2025-09-02
 
 ### ❗ Breaking Changes

README.md

@@ -45,6 +45,18 @@ const MetadataPresets: Record<string, MediaMetadataPublicFields>;
 
 An object containing several metadata presets we can use to retrieve metadata.
 
+### SaveFormat
+
+```ts
+const SaveFormat = {
+  JPEG: 'jpeg',
+  PNG: 'png',
+  WEBP: 'webp',
+};
+```
+
+Formats that we can save the image as.
+
 ## Functions
 
 ### getArtwork
@@ -108,10 +120,18 @@ Update internal configuration options such as the max size of the returned base6
 
 ```ts
 type ArtworkOptions = {
+  /**
+   * A value in the range `0.0` - `1.0` specifying the quality of the resulting image.
+   * - Defaults to `1`.
+   */
+  compress?: number;
+  /**
+   * Specifies the format the image will be saved in.
+   * - Defaults to `SaveFormat.JPEG`.
+   */
+  format?: SaveFormat;
   /** Uri we want to save the artwork to instead of the cache directory. */
   saveUri?: string;
-  /** Whether we should compress the saved image to 80% image quality. */
-  compress?: boolean;
 };
 ```
 

android/src/main/java/com/cyanchill/missingcore/metadataretriever/models/ArtworkOptions.kt

@@ -3,25 +3,59 @@ package com.cyanchill.missingcore.metadataretriever.models
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.ReadableMap
 
+import android.graphics.Bitmap
 import android.net.Uri
 import android.os.Bundle
 
 class ArtworkOptions(options: ReadableMap) {
   /** If we want to return the artwork as a base64 string. */
   val asBase64: Boolean
 
+  /** A value in the range `0.0` - `1.0` specifying the quality of the resulting image. */
+  val compress: Double
+  /** Specifies the format the image will be saved in. */
+  val format: ImageFormat
   /** Location where we want to save the image. */
   val saveUri: String?
-  /** Save the image at 80% quality. */
-  val compress: Boolean
 
   init {
     val optionsBundle = Arguments.toBundle(options) as Bundle
     asBase64 = optionsBundle.getBoolean("base64")
-    compress = optionsBundle.getBoolean("compress")
+
+    compress = if (optionsBundle.containsKey("compress")) optionsBundle.getDouble("compress") else 1.0
+    // Default format to JPEG if it's not provided.
+    format = ImageFormat.fromCode(optionsBundle.getString("format")) ?: ImageFormat.JPEG
 
     // Remove `file://` in `saveUri` if provided.
     val uri = optionsBundle.getString("saveUri")
     saveUri = if (uri != null) Uri.parse(uri).path else null
   }
 }
+
+enum class ImageFormat(val code: String) {
+  JPEG("jpeg"),
+  JPG("jpg"),
+  PNG("png"),
+  WEBP("webp");
+
+  val fileExtension: String
+    get() = when (this) {
+      JPEG, JPG -> ".jpg"
+      PNG -> ".png"
+      WEBP -> ".webp"
+    }
+
+  val compressFormat: Bitmap.CompressFormat
+    get() = when (this) {
+      JPEG, JPG -> Bitmap.CompressFormat.JPEG
+      PNG -> Bitmap.CompressFormat.PNG
+      WEBP -> Bitmap.CompressFormat.WEBP
+    }
+
+  companion object {
+    fun fromCode(code: String?): ImageFormat? {
+      if (code == null) return null
+      return entries.find { it.code == code }
+    }
+  }
+}

android/src/main/java/com/cyanchill/missingcore/metadataretriever/modules/MetadataReader.kt

@@ -179,12 +179,12 @@ class MetadataReader(reactContext: ReactApplicationContext): APIConfigs() {
   fun saveImage(bytes: ByteArray, options: ArtworkOptions): String? {
     try {
       // Generate path to save image if we didn't provide one.
-      val imgUri = options.saveUri ?: "$saveDirectory${File.separator}${UUID.randomUUID()}.jpeg"
+      val imgUri = options.saveUri ?: "$saveDirectory${File.separator}${UUID.randomUUID()}${options.format.fileExtension}"
       val bitmap = BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
       FileOutputStream(imgUri).use { fos ->
         bitmap.compress(
-          Bitmap.CompressFormat.JPEG,
-          if (options.compress) 80 else 100,
+          options.format.compressFormat,
+          (options.compress * 100).toInt(),
           fos,
         )
         fos.flush()

examples/benchmarking-demo/data/useTracksWithSavedArtwork.ts

@@ -38,7 +38,7 @@ async function getTracksWithSavedArtwork() {
   const tracksMetadata = await Promise.allSettled(
     results.results.map(async ({ uri, data }) => {
       const { id, filename } = assetURIMap[uri]!;
-      const imgUri = await saveArtwork(uri, { compress: true });
+      const imgUri = await saveArtwork(uri, { compress: 0.8 });
       return { id, filename, artworkData: imgUri, ...data };
     })
   );

src/index.ts

@@ -3,6 +3,7 @@ import MetadataRetriever from './MetadataRetriever';
 import { MetadataPresets } from './constants';
 
 import type { ArtworkOptions } from './types/ArtworkOptions';
+import { SaveFormat } from './types/ArtworkOptions';
 import type { ConfigOptions } from './types/ConfigOptions';
 import type { BulkMetadata, MediaMetadataExcerpt } from './types/GetMetadata';
 import type { MediaMetadata } from './types/MediaMetadata';
@@ -65,4 +66,5 @@ export {
   type MediaMetadataExcerpt,
   type MediaMetadataPublicField,
   MetadataPresets,
+  SaveFormat,
 };

src/types.utils.ts

@@ -2,3 +2,5 @@
 export type Prettify<T> = {
   [K in keyof T]: T[K];
 } & unknown;
+
+export type ObjectValues<T> = T[keyof T];

src/types/ArtworkOptions.ts

@@ -1,7 +1,25 @@
+import type { ObjectValues } from 'src/types.utils';
+
+export const SaveFormat = {
+  JPEG: 'jpeg',
+  PNG: 'png',
+  WEBP: 'webp',
+} as const;
+
+export type SaveFormat = ObjectValues<typeof SaveFormat>;
+
 /** Extra options for when using `getArtwork`. */
 export type ArtworkOptions = {
+  /**
+   * A value in the range `0.0` - `1.0` specifying the quality of the resulting image.
+   * - Defaults to `1`.
+   */
+  compress?: number;
+  /**
+   * Specifies the format the image will be saved in.
+   * - Defaults to `SaveFormat.JPEG`.
+   */
+  format?: SaveFormat;
   /** Uri we want to save the artwork to instead of the cache directory. */
   saveUri?: string;
-  /** Whether we should compress the saved image to 80% image quality. */
-  compress?: boolean;
 };

src/types/MediaMetadataPublicField.ts

@@ -1,3 +1,5 @@
+import type { ObjectValues } from 'src/types.utils';
+
 /**
  * Fields that can be extracted from media file.
  *
@@ -47,7 +49,8 @@ const MediaMetadataPublicFields = [
   'year',
 ] as const;
 
-export type MediaMetadataPublicField =
-  (typeof MediaMetadataPublicFields)[number];
+export type MediaMetadataPublicField = ObjectValues<
+  typeof MediaMetadataPublicFields
+>;
 
 export type MediaMetadataPublicFields = ReadonlyArray<MediaMetadataPublicField>;