程序包 io.agentscope.core.formatter

类 MediaUtils

java.lang.Object
io.agentscope.core.formatter.MediaUtils
public class MediaUtils extends Object
Utility class for handling media files in multimodal content. Provides methods for processing images, audio, and other media types.

  • 方法详细资料

    • isLocalFile

      public static boolean isLocalFile(String url)
      Check if a URL is a local file path (not a URL with protocol scheme). Returns true for paths without http://, https://, ftp://, file:// or oss:// prefixes. Used to distinguish local files from remote URLs for different processing paths.
      参数:
      url - The URL or file path to check
      返回:
      true if it's a local file path, false if it has a protocol scheme

    • fileToBase64

      public static String fileToBase64(String path) throws IOException
      Convert a local file to base64 encoded string. Validates file size before reading (max 50MB). Used when APIs require base64-encoded media content.
      参数:
      path - The local file path
      返回:
      Base64-encoded string of file contents
      抛出:
      IOException - If file cannot be read or exceeds size limit

    • downloadUrlToBase64

      public static String downloadUrlToBase64(String url) throws IOException
      Download a remote URL and convert to base64. Used for APIs that require base64 encoding instead of direct URLs (e.g., OpenAI audio). Validates downloaded size (max 50MB) and sets connection timeouts.
      参数:
      url - The remote URL to download
      返回:
      Base64-encoded string of downloaded content
      抛出:
      IOException - If download fails, exceeds size limit, or returns non-200 status

    • urlToProtocolUrl

      public static String urlToProtocolUrl(String url) throws IOException
      Convert a URL to a file:// protocol URL or leave as-is for web URLs.
      参数:
      url - URL or file path
      返回:
      file:// protocol URL or original URL (e.g., file:///absolute/path/image.png)
      抛出:
      IOException - If the file does not exist

    • toFileProtocolUrl

      public static String toFileProtocolUrl(String path) throws IOException
      Convert a local file path to file:// protocol URL. Resolves relative paths to absolute and validates file existence. Used for DashScope vision models which accept file:// protocol for local files.
      参数:
      path - Local file path (relative or absolute)
      返回:
      file:// protocol URL with absolute path (e.g., file:///absolute/path/image.png)
      抛出:
      IOException - If the file does not exist

    • urlToInputStream

      public static InputStream urlToInputStream(String url) throws IOException
      Convert a file or web URL to an InputStream.
      参数:
      url - The file or web URL
      返回:
      An InputStream for the resource
      抛出:
      IOException - If the resource read failed

    • urlToRgbaImageInputStream

      public static InputStream urlToRgbaImageInputStream(String url) throws IOException
      Convert a file or web URL to an InputStream with RGBA image.
      参数:
      url - a local file path or web URL
      返回:
      an InputStream with RGBA image
      抛出:
      IOException - if the resource convert failed
      IllegalArgumentException - if the resource read failed

    • urlToBase64DataUrl

      public static String urlToBase64DataUrl(String url) throws IOException
      Convert a file or web URL to a data URL with base64 encoding.
      参数:
      url - a local file path or web url
      返回:
      a data URL with base64 encoding, the format is data:{mediaType};base64,{base64Data}
      抛出:
      IOException

    • determineMediaType

      public static String determineMediaType(String path)
      Determine MIME type from file extension.

    • validateImageExtension

      public static void validateImageExtension(String url)
      Validate that an image file has a supported extension.

    • validateAudioExtension

      public static void validateAudioExtension(String url)
      Validate that an audio file has a supported extension.

    • validateVideoExtension

      public static void validateVideoExtension(String url)
      Validate that a video file has a supported extension.

    • determineAudioFormat

      public static String determineAudioFormat(String path)
      Determine audio format string from file extension.
      参数:
      path - The file path
      返回:
      Audio format string ("wav" or "mp3")

    • inferAudioFormatFromMediaType

      public static String inferAudioFormatFromMediaType(String mediaType)
      Infer audio format string from MIME type.
      参数:
      mediaType - The MIME type
      返回:
      Audio format string ("wav", "mp3", "opus", "flac", etc.)

    • getExtension

      public static String getExtension(String path)
      Extract file extension from path or URL.

    • isFileExists

      public static boolean isFileExists(String path)
      Check if a file exists.
      参数:
      path - a local file path or URL.
      返回:
      true: exists, false: not exists or path is invalid