API: Media

オブジェクトにメディアリファレンスプロパティがある場合、関数を使用して関連するメディアアイテムと対話することができます。メディアアイテムは、基礎となるメディアと便利に対話するための多くのメソッドを提供します。外部ライブラリを使用せずに、さまざまな種類のメディアと簡単に対話できる多くの組み込み操作があります。以下のドキュメントでは、利用可能な機能とその使用方法について説明します。

現在すぐに利用できない操作が必要な場合は、おそらく外部ライブラリを使用するか、カスタムコードを作成する必要があります。Functions リポジトリに NPM 依存関係を追加する方法についてはこちらをご覧ください。

ユニバーサル操作

すべてのメディアタイプでサポートされている操作があります。

生メディアデータの読み取り

メディアアイテムから生データを読み取るには、メディアアイテムの readAsync メソッドを使用します。オブジェクトのメディアリファレンスプロパティを選択することで、メディアアイテムにアクセスできます。readAsync メソッドのシグネチャは以下の通りです:

Copied!
1
2
// 非同期で読み込みを行う
readAsync(): Promise<Blob>;

Blob は、変更不可能な生のデータのファイルのようなオブジェクトを表す標準的なJavaScript タイプ ↗です。上記のように、ライブラリを使用してデフォルトの機能を超えてメディアとやり取りすることができます。

メディアメタデータの取得

メディアアイテムのメタデータを取得するには、メディアアイテム上の getMetadataAsync メソッドを使用します。getMetadataAsync メソッドのシグネチャは以下の通りです。

Copied!
1
2
// 非同期でメタデータを取得する関数
getMetadataAsync(): Promise<IMediaMetadata>;

タイプガード

いくつかのタイプガードが利用可能で、特定のメディアタイプに特有の機能にアクセスすることができます。メディアアイテムのメタデータに使用できるタイプガードは次の通りです：

• isAudioMetadata()
• isDicomMetadata()
• isDocumentMetadata()
• isImageryMetadata()
• isVideoMetadata()

例えば、画像タイプガードを使用して、画像に特有のメタデータフィールドを抽出することができます：

Copied!
1
2
3
4
5
6
7
8
9
const metadata = await myObject.mediaReference?.getMetadataAsync();
// mediaReferenceが存在する場合、非同期でメタデータを取得する

if (isImageryMetadata(metadata)) {
    // メタデータが画像の情報である場合
    const imageWidth = metadata.dimensions?.width;
    // 画像の幅を取得する
    ...
}

メディアアイテム名前空間で型ガードを使用することもできます。これにより、型固有のメディアアイテムに対するより多くのメソッドにアクセスできます。ここで使用できる型ガードは次のとおりです:

• MediaItem.isAudio()
• MediaItem.isDocument()
• MediaItem.isImagery()

ドキュメント固有の操作

テキスト抽出

ドキュメントからテキストを抽出するには、メディアアイテムの ocrAsync または extractTextAsync メソッドを使用できます。

機械生成されたPDFの場合、光学文字認識（OCR）を使用するよりも、PDFにデジタルで埋め込まれたテキストを抽出する方が速く、またはより正確である可能性があります。以下にテキスト抽出の使用例を示します: 以下はオプションで TypeScript オブジェクトとして提供できます：

• startPage: ゼロインデックスの開始ページ（含む）。
• endPage: ゼロインデックスの終了ページ（含まない）。

機械生成されていない PDF については、テキスト抽出には OCR メソッドを使用するのが最適です。

Copied!
1
ocrAsync(options: IDocumentOcrOptions): Promise<string[]>;

Copied!
1
2
3
4
5
6
/**
 * 非同期でOCR（光学文字認識）を実行する関数。
 * @param options - ドキュメントOCRオプションを指定するパラメータ。
 * @returns 認識された文字列の配列をPromiseで返す。
 */
ocrAsync(options: IDocumentOcrOptions): Promise<string[]>;

Copied!
1
2
// 非同期でテキストを抽出する関数
extractTextAsync(options: IDocumentExtractTextOptions): Promise<string[]>;

以下はオプションで TypeScript オブジェクトとして提供できます。

• startPage: 0 インデックスの開始ページ（含む）。
• endPage: 0 インデックスの終了ページ（除外）。
• languages: 認識する言語のリスト（空でも可）。
• scripts: 認識するスクリプトのリスト（空でも可）。
• outputType: text または hocr として出力タイプを指定。

メディアタイプ特有の操作にアクセスするには、型ガードを使用する必要があります。次に、isDocument 型ガードを使用して OCR テキスト抽出を実行する例を示します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { MediaItem } from "@foundry/functions-api";
import { ArxivPaper } from "@foundry/ontology-api";

@Function()
public async firstPageText(paper: ArxivPaper): Promise<string | undefined> {
    // mediaReferenceがDocumentであるかを確認
    if (MediaItem.isDocument(paper.mediaReference!)) {
        // OCRを使って最初のページのテキストを抽出
        const text = (await paper.mediaReference.ocrAsync({ endPage: 1, languages: [], scripts: [], outputType: 'text' }))[0];
        return text;
    }

    // mediaReferenceがDocumentでない場合はundefinedを返す
    return undefined;
}

Copied!
1
2
// 非同期で音声を文字起こしするための関数です。IAudioTranscriptionOptionsというインターフェースのオプションを引数として取り、Promise<string>型を返します。
transcribeAsync(options: IAudioTranscriptionOptions): Promise<string>;

Audio-specific operations

Transcription

音声メディアアイテムは transcribeAsync メソッドを使用して文字起こしをサポートします。シグネチャは以下の通りです: 以下のオプションを指定して、トランスクリプションの実行方法をオプションで設定できます。利用可能なオプションは次のとおりです：

• language: TranscriptionLanguage enum を使用して渡されるトランスクリプトの言語。
• performanceMode: TranscriptionPerformanceMode enum を使用して、More Economical または More Performant モードでトランスクリプションを実行。
• outputFormat: type が plainTextNoSegmentData（プレーンテキスト）または pttml のオブジェクトを渡して出力フォーマットを指定。pttml は TTML-like ↗️ フォーマットで、タイプが plainTextNoSegmentData の場合、オブジェクトは boolean の addTimestamps パラメーターも取る。

以下は、トランスクリプションのオプションを提供する例です：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { Function, MediaItem, TranscriptionLanguage, TranscriptionPerformanceMode } from "@foundry/functions-api";
import { AudioFile } from "@foundry/ontology-api";

@Function()
public async transcribeAudioFile(file: AudioFile): Promise<string|undefined> {
    // メディア参照がオーディオファイルであるかを確認
    if (MediaItem.isAudio(file.mediaReference!)) {
        // オーディオファイルを非同期で文字起こし
        return await file.mediaReference.transcribeAsync({
            language: TranscriptionLanguage.ENGLISH, // 文字起こしの言語を英語に設定
            performanceMode: TranscriptionPerformanceMode.MORE_ECONOMICAL, // パフォーマンスモードを「より経済的」に設定
            outputFormat: {type: "plainTextNoSegmentData", addTimestamps: true} // 出力フォーマットをプレーンテキストに設定し、タイムスタンプを追加
        });
    }

    return undefined; // オーディオファイルでない場合、undefinedを返す
}