Widgets/Transformer

Data to Binary File Widget

Data to Binary File Widget

A "Transformer" type widget. Data to Binary File Widget converts various supported input data types into a BinaryFile format with a specified MIME type and file name. This widget is essential for preparing data for file operations, downloads, or storage in binary formats.

The widget handles different input types and validates compatibility between the input data and the target MIME type to prevent invalid conversions.

 

Inputs

  • data (DataTypes: ImageData, ArrayBuffer, String, Anything) The input data to be converted into a BinaryFile. The widget supports multiple input types:

    • ImageData: Image data that can be converted to PNG or JPEG formats
    • ArrayBuffer: Binary data that can be used with any MIME type
    • String: Text data that can be encoded for text-based MIME types
    • Anything: Any data type that can be safely converted based on the target MIME type

  • name (DataType: String) A dynamic input port that allows you to set the file name at runtime, overriding the File Name setting. When a value is provided through this port and the workflow executes, that value automatically overwrites the File Name field in the widget settings, and the widget uses this dynamic name for file processing.

    Important: When providing the file name through the name input port, you must explicitly include the file extension (e.g., .txt, .png, .json, .csv). If the extension is not present, the file may not be processed correctly.


Outputs

  • file (DataType: BinaryFile) Outputs a BinaryFile object containing:
    • format: The MIME type specified in the widget settings
    • fileName: The file name from the name input port (if provided) or from the File Name setting
    • data: An ArrayBuffer containing the encoded data

Custom Settings

The Data to Binary File widget offers customization through its settings panel:

Mime Type

  • Mime Type (DataType: String): The target MIME type for the output file. This field supports:
    • A searchable dropdown with common MIME types (e.g., image/png, image/jpeg, application/json, text/plain, audio/mpeg, video/mp4)
    • Custom MIME types: You can type any valid MIME type directly into the field
    • Default value: application/octet-stream

Common MIME types available:

  • Images: image/png, image/jpeg
  • Documents: application/pdf, application/json, application/xml, application/zip
  • Text: text/plain, text/csv, text/html, text/markdown
  • Audio: audio/mpeg, audio/ogg, audio/mp3
  • Video: video/mp4, video/ogg
  • Generic: application/octet-stream

File Name

  • File Name (DataType: String): The name of the output file (without path). This field is displayed directly on the widget body for quick access.
    • Default value: output.bin
    • The file name should include an appropriate extension matching the MIME type (e.g., .png for image/png, .json for application/json)

Mime Type Setting

 

Input Type Compatibility

The widget validates input types against the target MIME type to ensure compatibility:

ImageData Inputs

  • Compatible with: image/png, image/jpeg (and other image/* MIME types)
  • Conversion: Uses the canvas manager for cross-environment image encoding
  • Limitation: Only PNG and JPEG are fully supported for ImageData inputs

ArrayBuffer Inputs

  • Compatible with: Any MIME type
  • Behavior: Passes through the binary data as-is

String Inputs

  • Compatible with:
    • Text-based MIME types (text/*)
    • application/json and JSON-like types (*+json)
    • application/xml and XML-like types (*+xml)
    • application/octet-stream (generic binary)
  • Not compatible with: Audio/video MIME types (require ArrayBuffer)

BinaryFile Inputs

  • Compatible with:
    • Same MIME type as input (pass-through)
    • application/octet-stream (generic binary pass-through)
    • Image to image conversion (when both are supported image formats)

Anything Inputs

  • Compatible with:
    • Text-based MIME types (data is JSON-stringified)
    • application/json (data is JSON-stringified)
  • Not compatible with: Audio/video MIME types (require ArrayBuffer)

 

Examples

Converting Base64 Image to PNG and Saving to File System

This example demonstrates a complete workflow for converting a Base64-encoded image string to a PNG BinaryFile and automatically saving it to the file system. The workflow includes:


Drag the example onto the workspace to explore and experiment!



In this example:

  1. The Play Widget triggers the workflow execution
  2. The Text Widget provides a Base64-encoded image data string containing the image to be converted
  3. The Base64 to ImageData Widget converts the Base64 string into ImageData format, making it ready for image processing
  4. The Data to Binary File Widget converts the ImageData to a PNG BinaryFile with the file name new-image.png and MIME type image/png
  5. The Sequence Widget coordinates the file writing operation by ensuring proper ordering: first providing the BinaryFile to the File System service, then triggering the write operation
  6. The File System Service (Write Contents Variant) receives the BinaryFile and write trigger, then writes the file to disk at the specified path configured in the widget settings. The file is created if it doesn't exist, or overwritten based on the "Append to File" setting. The service returns a success status indicating whether the operation completed successfully

 

Converting CSV String to CSV File with Dynamic Filename

This example demonstrates a complete workflow for converting a CSV-formatted string to a CSV BinaryFile with a dynamically generated file name based on the current date, and automatically saving it to the file system. The workflow includes:


Drag the example onto the workspace to explore and experiment!



In this example:

  1. The Play Widget triggers the workflow execution
  2. The Sequence Widget coordinates the initial workflow steps: first triggering the Expression Eval widget to generate the dynamic file name, then triggering the Text widget to provide the CSV data
  3. The Expression Eval Widget generates a dynamic file name based on the current date using the expression "users-" + date.year + "-" + date.month + "-" + date.day + ".csv", which produces a file name like users-2026-1-7.csv
  4. The Text Widget provides a CSV-formatted string "ID,Name\n1,John\n2,Alex" containing the data to be converted
  5. The Data to Binary File Widget receives the CSV string through the data input port and the dynamic file name through the name input port. The widget converts the string to a CSV BinaryFile with the dynamically generated file name (e.g., users-2026-1-7.csv) and MIME type text/csv. The name input port overrides the default File Name setting at runtime
  6. The Sequence Widget coordinates the file writing operation: first providing the BinaryFile to the File System service, then triggering the write operation
  7. The File System Service (Write Contents Variant) receives the BinaryFile and write trigger, then writes the file to disk at the specified path configured in the widget settings. The file is created if it doesn't exist, or overwritten based on the "Append to File" setting

 

📌 Additional Notes

  • Image Conversion: When converting ImageData to PNG or JPEG, the widget uses the canvas manager for cross-environment compatibility (works in both browser and Node.js environments)
  • MIME Type Validation: The widget performs runtime validation to ensure input types are compatible with the target MIME type. Incompatible combinations will throw descriptive error messages
  • Custom MIME Types: You can enter any valid MIME type in the settings, not just those in the dropdown list
  • File Name Extension: While not strictly required, it's recommended to use file extensions that match the MIME type (e.g., .png for image/png, .json for application/json)
  • BinaryFile Pass-through: When the input is already a BinaryFile with a matching MIME type, the widget can pass it through without re-encoding (unless converting between image formats)
  • String Encoding: String inputs are encoded using UTF-8 encoding when converted to ArrayBuffer
  • Error Handling: The widget provides clear error messages when:
    • Input type is incompatible with the target MIME type
    • File name is missing
    • Image conversion fails
    • Unsupported image format is requested

 

Glossary

  • ArrayBuffer

    A JavaScript object used to represent a generic, fixed-length raw binary data buffer.

  • BinaryFile

    A data type in Kemu that represents a file with binary data, containing format (MIME type), fileName, and data (ArrayBuffer) properties.

  • Canvas Manager

    A utility in Kemu that provides cross-environment canvas operations, allowing image processing to work consistently in both browser and Node.js environments.

  • File System Service

    A Hub Service in Kemu that allows interaction with the file system. It provides functionalities to scan directories, filter files based on glob patterns or MIME types, read file contents, write contents to files, delete files and directories, and convert binary files to text. The service includes multiple variants such as Scan, Read Contents, Write Contents, and Filter variants for different file system operations.

  • ImageData

    A data type in Kemu representing image pixel data with width, height, and pixel array information.

  • MIME Type

    A standard way of indicating the nature and format of a document or file. Examples include image/png, application/json, text/plain.