UtaFormatix3

During the import process, UtaFormatix3 may emit ImportWarning objects to notify the user of non-fatal issues such as missing metadata, ignored tempo/time signature settings, or version mismatches. These warnings allow the import to proceed while informing the user of potential data discrepancies.

Available warning types include:

• Tempo Issues:
  • TempoNotFound: No tempo information was found.
  • TempoIgnoredInFile(file, tempo): A specific tempo in the file was ignored.
  • TempoIgnoredInTrack(track, tempo): A tempo within a specific track was ignored.
  • TempoIgnoredInPreMeasure(tempo): A tempo in a pre-measure was ignored.
  • DefaultTempoFixed(originalBpm): The original BPM was invalid or missing, and a default tempo was applied.
• Time Signature Issues:
  • TimeSignatureNotFound: No time signature information was found.
  • TimeSignatureIgnoredInTrack(track, timeSignature): A time signature within a specific track was ignored.
  • TimeSignatureIgnoredInPreMeasure(timeSignature): A time signature in a pre-measure was ignored.
• Version Issues:
  • IncompatibleFormatSerializationVersion(currentVersion, dataVersion): The data version is incompatible with the current software version.

// Example of handling specific warning types
when (warning) {
    is ImportWarning.TempoNotFound -> println("Warning: No tempo found.")
    is ImportWarning.DefaultTempoFixed -> println("Warning: Fixed BPM from ${warning.originalBpm}")
    is ImportWarning.IncompatibleFormatSerializationVersion -> println("Version mismatch: ${warning.dataVersion} vs ${warning.currentVersion}")
    // ... handle other cases
}

When working with UtaFormatix3, you may encounter IllegalFileException when attempting to load or parse files that are corrupted, use an unsupported version, or do not match the expected format. This is a sealed class, meaning you can use exhaustive pattern matching (e.g., when in Kotlin) to handle specific failure cases.

Common error subtypes include:

• UnknownVsqVersion: The .vsqx file version cannot be identified.
• XmlRootNotFound: The XML file is missing its root element.
• XmlElementNotFound(name): A required XML element <name> is missing.
• XmlElementValueIllegal(name): A required XML element <name> contains an invalid value.
• XmlElementAttributeValueIllegal(attribute, elementName): An attribute is missing or invalid within a specific element.
• IllegalMidiFile: The file cannot be parsed as a MIDI file.
• IllegalTsslnFile: The file cannot be parsed as a .tssln file.

try {
    // Attempt to load a file
} catch (e: IllegalFileException) {
    when (e) {
        is IllegalFileException.UnknownVsqVersion -> println("Version error")
        is IllegalFileException.XmlRootNotFound -> println("XML structure error")
        is IllegalFileException.XmlElementNotFound -> println("Missing element: ${e.message}")
        // ... handle other cases
        else -> println("General file error: ${e.message}")
    }
}