类class io.agentscope.core.formatter 2.x

MediaUtils

public class MediaUtils

源码Source io/agentscope/core/formatter/MediaUtils.java:44–449

Media Utils，在智能体、模型与前端之间传递结构化消息和事件。位于 io.agentscope.core.formatter 包。核心成员包括 isLocalFile、fileToBase64、downloadUrlToBase64、urlToProtocolUrl、toFileProtocolUrl、urlToInputStream。

Utility class for handling media files in multimodal content. Provides methods for processing images, audio, and other media types.

方法摘要Method Summary

方法Method	说明Description
`public static boolean isLocalFile(String url)` static	判断是否本地文件。 Check if a URL is a local file path (not a URL with protocol scheme).
`public static String fileToBase64(String path) throws IOException` static	设置文件到基类 64。 Convert a local file to base64 encoded string.
`public static String downloadUrlToBase64(String url) throws IOException` static	设置下载 URL 到基类 64。 Download a remote URL and convert to base64.
`public static String urlToProtocolUrl(String url) throws IOException` static	设置URL 到协议 URL。 Convert a URL to a file:// protocol URL or leave as-is for web URLs.
`public static String toFileProtocolUrl(String path) throws IOException` static	转换本地文件路径到文件://协议 URL。 Convert a local file path to file:// protocol URL.
`public static InputStream urlToInputStream(String url) throws IOException` static	设置URL 到输入流。 Convert a file or web URL to an InputStream.
`public static InputStream urlToRgbaImageInputStream(String url) throws IOException` static	设置该参数。 Convert a file or web URL to an InputStream with RGBA image.
`public static String urlToBase64DataUrl(String url) throws IOException` static	设置URL 到基类 64 数据 URL。 Convert a file or web URL to a data URL with base64 encoding.
`public static String determineMediaType(String path)` static	设置该参数。 Determine MIME type from file extension.
`public static String resolveMimeType(Source source)` static	解析MIME 类型。 Resolve the MIME type from a `Source`.
`public static void validateImageExtension(String url)` static	校验图像扩展。 Validate that an image file has a supported extension.
`public static void validateAudioExtension(String url)` static	校验音频扩展。 Validate that an audio file has a supported extension.
`public static void validateVideoExtension(String url)` static	校验视频扩展。 Validate that a video file has a supported extension.
`public static String determineAudioFormat(String path)` static	设置该参数。 Determine audio format string from file extension.
`public static String inferAudioFormatFromMediaType(String mediaType)` static	设置该参数。 Infer audio format string from MIME type.
`public static String getExtension(String path)` static	获取扩展。 Extract file extension from path or URL.
`public static boolean isFileExists(String path)` static	判断是否 `isFileExists`。 Check if a file exists.

方法详情Method Detail

isLocalFile

public static boolean isLocalFile(String url)

static

判断是否本地文件。

Check if a URL is a local file path (not a URL with protocol scheme).

参数Parameters

名称Name	类型Type	说明Description
`url`	String	URL 或文件路径到检查。The URL or file path to check

返回Returns boolean

返回布尔值，表示判断结果。true if it's a local file path, false if it has a protocol scheme

源码Source io/agentscope/core/formatter/MediaUtils.java:71–80

fileToBase64

public static String fileToBase64(String path) throws IOException

static

设置文件到基类 64。

Convert a local file to base64 encoded string.

参数Parameters

名称Name	类型Type	说明Description
`path`	String	本地文件路径。The local file path

返回Returns String

返回字符串结果。Base64-encoded string of file contents

抛出Throws

IOException 可能抛出 `IOException`。Thrown when the operation cannot be completed.

源码Source io/agentscope/core/formatter/MediaUtils.java:91–102

downloadUrlToBase64

public static String downloadUrlToBase64(String url) throws IOException

static

设置下载 URL 到基类 64。

Download a remote URL and convert to base64.

参数Parameters

名称Name	类型Type	说明Description
`url`	String	远程 URL 到下载。The remote URL to download

返回Returns String

返回字符串结果。Base64-encoded string of downloaded content

抛出Throws

IOException 可能抛出 `IOException`。Thrown when the operation cannot be completed.

源码Source io/agentscope/core/formatter/MediaUtils.java:113–150

urlToProtocolUrl

public static String urlToProtocolUrl(String url) throws IOException

static

设置URL 到协议 URL。

Convert a URL to a file:// protocol URL or leave as-is for web URLs.

参数Parameters

名称Name	类型Type	说明Description
`url`	String	服务地址（类型 `String`）。URL or file path

返回Returns String

返回字符串结果。file:// protocol URL or original URL (e.g., file:///absolute/path/image.png)

抛出Throws

IOException 可能抛出 `IOException`。Thrown when the operation cannot be completed.

源码Source io/agentscope/core/formatter/MediaUtils.java:159–165

toFileProtocolUrl

public static String toFileProtocolUrl(String path) throws IOException

static

转换本地文件路径到文件://协议 URL。

Convert a local file path to file:// protocol URL.

参数Parameters

名称Name	类型Type	说明Description
`path`	String	路径（类型 `String`）。Local file path (relative or absolute)

返回Returns String

返回字符串结果。file:// protocol URL with absolute path (e.g., file:///absolute/path/image.png)

抛出Throws

IOException 可能抛出 `IOException`。Thrown when the operation cannot be completed.

源码Source io/agentscope/core/formatter/MediaUtils.java:176–182

urlToInputStream

public static InputStream urlToInputStream(String url) throws IOException

static

设置URL 到输入流。

Convert a file or web URL to an InputStream.

参数Parameters

名称Name	类型Type	说明Description
`url`	String	服务地址（类型 `String`）。The file or web URL

返回Returns InputStream

一种InputStream 用于资源。An InputStream for the resource

抛出Throws

IOException 可能抛出 `IOException`。Thrown when the operation cannot be completed.

源码Source io/agentscope/core/formatter/MediaUtils.java:191–199

urlToRgbaImageInputStream

public static InputStream urlToRgbaImageInputStream(String url) throws IOException

static

设置该参数。

Convert a file or web URL to an InputStream with RGBA image.

参数Parameters

名称Name	类型Type	说明Description
`url`	String	服务地址（类型 `String`）。a local file path or web URL

返回Returns InputStream

一种InputStream 使用 RGBA 图像。an InputStream with RGBA image

抛出Throws

IOException 可能抛出 `IOException`。Thrown when the operation cannot be completed.

源码Source io/agentscope/core/formatter/MediaUtils.java:208–226

urlToBase64DataUrl

public static String urlToBase64DataUrl(String url) throws IOException

static

设置URL 到基类 64 数据 URL。

Convert a file or web URL to a data URL with base64 encoding.

参数Parameters

名称Name	类型Type	说明Description
`url`	String	服务地址（类型 `String`）。a local file path or web url

返回Returns String

返回字符串结果。a data URL with base64 encoding, the format is data:{mediaType};base64,{base64Data}

抛出Throws

IOException 可能抛出 `IOException`。Thrown when the operation cannot be completed.

源码Source io/agentscope/core/formatter/MediaUtils.java:233–245

determineMediaType

public static String determineMediaType(String path)

static

设置该参数。

Determine MIME type from file extension.

参数Parameters

名称Name	类型Type	说明Description
`path`	String	路径（类型 `String`）。The path.

返回Returns String

返回字符串结果。Returns a string.

源码Source io/agentscope/core/formatter/MediaUtils.java:250–281

resolveMimeType

public static String resolveMimeType(Source source)

static

解析MIME 类型。

Resolve the MIME type from a Source.

参数Parameters

名称Name	类型Type	说明Description
`source`	Source	来源到解析 MIME 类型来自。the source to resolve MIME type from

返回Returns String

返回字符串结果。MIME type string (e.g. "image/jpeg")

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if the type cannot be determined or source type is unknown

源码Source io/agentscope/core/formatter/MediaUtils.java:297–316

validateImageExtension

public static void validateImageExtension(String url)

static

校验图像扩展。

Validate that an image file has a supported extension.

参数Parameters

名称Name	类型Type	说明Description
`url`	String	服务地址（类型 `String`）。The url.

源码Source io/agentscope/core/formatter/MediaUtils.java:321–328

validateAudioExtension

public static void validateAudioExtension(String url)

static

校验音频扩展。

Validate that an audio file has a supported extension.

参数Parameters

名称Name	类型Type	说明Description
`url`	String	服务地址（类型 `String`）。The url.

源码Source io/agentscope/core/formatter/MediaUtils.java:333–341

validateVideoExtension

public static void validateVideoExtension(String url)

static

校验视频扩展。

Validate that a video file has a supported extension.

参数Parameters

名称Name	类型Type	说明Description
`url`	String	服务地址（类型 `String`）。The url.

源码Source io/agentscope/core/formatter/MediaUtils.java:346–354

determineAudioFormat

public static String determineAudioFormat(String path)

static

设置该参数。

Determine audio format string from file extension.

参数Parameters

名称Name	类型Type	说明Description
`path`	String	文件路径。The file path

返回Returns String

返回字符串结果。Audio format string ("wav" or "mp3")

源码Source io/agentscope/core/formatter/MediaUtils.java:362–365

inferAudioFormatFromMediaType

public static String inferAudioFormatFromMediaType(String mediaType)

static

设置该参数。

Infer audio format string from MIME type.

参数Parameters

名称Name	类型Type	说明Description
`mediaType`	String	MIME 类型。The MIME type

返回Returns String

返回字符串结果。Audio format string ("wav", "mp3", "opus", "flac", etc.)

源码Source io/agentscope/core/formatter/MediaUtils.java:373–385

getExtension

public static String getExtension(String path)

static

获取扩展。

Extract file extension from path or URL.

参数Parameters

名称Name	类型Type	说明Description
`path`	String	路径（类型 `String`）。The path.

返回Returns String

返回字符串结果。Returns a string.

源码Source io/agentscope/core/formatter/MediaUtils.java:390–418

isFileExists

public static boolean isFileExists(String path)

static

判断是否 isFileExists。

Check if a file exists.

参数Parameters

名称Name	类型Type	说明Description
`path`	String	一种本地文件路径或 URL。a local file path or URL.

返回Returns boolean

返回布尔值，表示判断结果。true: exists, false: not exists or path is invalid

源码Source io/agentscope/core/formatter/MediaUtils.java:425–434