Komf Documentation

By default, Komf fetches metadata from only the first provider that returns a positive match based on priority.

To enable metadata aggregation, set aggregateMetadata: true in your configuration. When enabled:

1. Initial metadata is taken from the highest priority provider that returns a match.
2. Komf then queries all other configured providers.
3. Metadata fields are filled in from subsequent providers only if the previous provider did not have data for that specific field (e.g., if Provider A has a title but no thumbnail, the thumbnail will be pulled from Provider B).

You can granularly control which fields are fetched from a provider by setting them to true or false within the seriesMetadata or bookMetadata blocks of a provider's configuration.

metadataProviders:
  default:
    mangaUpdates:
      priority: 10
      enabled: true
      seriesMetadata:
        thumbnail: false # Disables thumbnail fetching for this provider
      bookMetadata:
        title: true
        summary: true

Use Docker Compose to orchestrate Komf. This method allows you to configure Komga/Kavita credentials and JVM options via environment variables.

Note: Ensure you map a volume to /config to persist your application.yml and the SQLite database.

version: "3.7"
services:
  komf:
    image: sndxr/komf:latest
    container_name: komf
    ports:
      - "8085:8085"
    user: "1000:1000"
    environment:
      - KOMF_KOMGA_BASE_URI=http://komga:25600
      - KOMF_KOMGA_USER=admin@example.org
      - KOMF_KOMGA_PASSWORD=admin
      - KOMF_KAVITA_BASE_URI=http://kavita:5000
      - KOMF_KAVITA_API_KEY=16707507-d05d-4696-b126-c3976ae14ffb
      - KOMF_LOG_LEVEL=INFO
      - JAVA_TOOL_OPTIONS=-XX:+UnlockExperimentalVMOptions -XX:+UseShenandoahGC -XX:ShenandoahGCHeuristics=compact -XX:ShenandoahGuaranteedGCInterval=3600000 -XX:TrimNativeHeapInterval=3600000
    volumes:
      - /path/to/config:/config
    restart: unless-stopped

The Infobox sealed interface represents structured metadata fields provided by Bangumi. Because the underlying JSON format varies (sometimes a single string, sometimes an array of objects), it uses a custom polymorphic serializer (InfoBoxSerializer) to handle two distinct shapes:

1. SingleValue: Used when the value field in the JSON is a primitive (e.g., a string).
2. MultipleValues: Used when the value field in the JSON is an array of InfoboxNestedValue objects.

InfoboxNestedValue

When using MultipleValues, each nested item contains:

• key: An optional string identifier.
• value: The actual string value.

val infoboxes: List<Infobox> = listOf(
    Infobox.SingleValue(key = "Author", value = "John Doe"),
    Infobox.MultipleValues(
        key = "Cast",
        value = listOf(
            InfoboxNestedValue(key = "Actor A", value = "Role A"),
            InfoboxNestedValue(key = "Actor B", value = "Role B")
        )
    )
)

When performing partial updates (PATCH requests) via the Komf API, use the PatchValue<T> sealed class to distinguish between three states for a field:

1. PatchValue.Unset: The field should not be included in the request (no change).
2. PatchValue.None: The field should be explicitly set to null in the API request.
3. PatchValue.Some(value): The field should be updated to the provided value.

You can use the patch(original, patch) helper function to automatically determine the correct state by comparing the current value with the desired new value.

// Example of determining a patch state
val originalValue: String? = "Old Title"
val newValue: String? = "New Title"

val patchState = patch(originalValue, newValue)
// patchState is PatchValue.Some("New Title")

val noChange: PatchValue<String> = patch(originalValue, originalValue)
// noChange is PatchValue.Unset

val setToNull: PatchValue<String> = patch(originalValue, null)
// setToNull is PatchValue.None

You can define library-specific metadata update settings using the komga_or_kavita.metadataUpdate configuration key. If a library ID is not explicitly listed under library, the default settings will be applied. Use the actual Kavita or Komga library IDs as the keys for library-specific overrides.

Available configuration options include:

• updateModes: A list of modes (e.g., [ API ]).
• aggregate: Boolean to enable/disable metadata aggregation.
• bookCovers: Boolean to enable/disable book cover updates.
• seriesCovers: Boolean to enable/disable series cover updates.
• postProcessing: A nested object for fine-tuning metadata (e.g., seriesTitle, titleType, languageValue).

komga_or_kavita:
  metadataUpdate:
    default:
      aggregate: false
    library:
      09PERX1TW8GEK:
        updateModes: [ API ]
        aggregate: false
        bookCovers: false
        seriesCovers: false
        postProcessing:
          seriesTitle: false
          titleType: LOCALIZED
          alternativeSeriesTitles: false
          languageValue:
      123:
        aggregate: true
        seriesCovers: true

Komf is configured using an application.yml file. Key configuration sections include:

• komga / kavita: Connection details (baseUri, user/apiKey) and eventListener settings to enable automatic updates when new items are added.
• metadataUpdate: Defines how metadata is fetched (updateModes: API or COMIC_INFO), whether to aggregate from multiple providers, and post-processing rules (e.g., seriesTitle, languageValue, orderBooks).
• notifications: Configures Discord webhooks or Apprise URLs to send updates.
• database: Specifies the location of the database.sqlite file.
• metadataProviders: Configures API keys and priorities for various providers like mal, comicVine, mangaDex, etc.

komga:
  baseUri: http://localhost:25600
  komgaUser: admin@example.org
  komgaPassword: admin
  eventListener:
    enabled: false
    metadataLibraryFilter: [ ]
  metadataUpdate:
    default:
      libraryType: "MANGA"
      updateModes: [ API ]
      aggregate: false
      bookCovers: false
      seriesCovers: false
      overrideExistingCovers: true
      postProcessing:
        seriesTitle: false
        seriesTitleLanguage: "en"

metadataProviders:
  malClientId: ""
  comicVineApiKey: ""
  defaultProviders:
    mangaDex:
      enabled: false
      coverLanguages: ["en", "ja"]