@next2d/media 2.13.1 → 3.0.1

package/README.md

@@ -1,11 +1,355 @@
-@next2d/renderer
-=============
+# @next2d/media
 
-## Installation
+## Overview / 概要
 
+The `@next2d/media` package provides audio and video playback management using Web Audio API and HTML5 Video. This package enables Flash-like multimedia experiences in modern web applications.
+
+`@next2d/media` パッケージは、Web Audio API と HTML5 Video を使用した音声および動画の再生管理を提供します。このパッケージにより、モダンなWebアプリケーションでFlashのようなマルチメディア体験を実現できます。
+
+## Features / 機能
+
+- **Sound Playback**: MP3/audio file loading and playback with Web Audio API / Web Audio APIを使用したMP3/音声ファイルの読み込みと再生
+- **Video Playback**: HTML5 video element integration with custom rendering pipeline / HTML5動画要素の統合とカスタムレンダリングパイプライン
+- **Global Audio Control**: Application-wide volume and playback management / アプリケーション全体の音量と再生管理
+- **Sound Transform**: Volume and loop control for individual sounds / 個別のサウンドの音量とループ制御
+
+## Installation / インストール
+
+```bash
+npm install @next2d/media
+```
+
+## Directory Structure / ディレクトリ構造
+
+```
+src/
+├── Sound.ts                          # Sound class for audio playback / 音声再生用のSoundクラス
+├── Sound/
+│   ├── service/                      # Sound-related services / Sound関連のサービス
+│   │   ├── SoundDecodeService.ts     # ArrayBuffer to AudioBuffer decoding / ArrayBufferからAudioBufferへのデコード
+│   │   ├── SoundEndedEventService.ts # Sound ended event handling / サウンド終了イベント処理
+│   │   ├── SoundLoadStartEventService.ts # Load start event / 読み込み開始イベント
+│   │   └── SoundProgressEventService.ts  # Load progress event / 読み込み進捗イベント
+│   └── usecase/                      # Sound use cases / Soundユースケース
+│       ├── SoundBuildFromCharacterUseCase.ts # Build from character data / キャラクターデータからの構築
+│       ├── SoundLoadEndEventUseCase.ts # Load completion handling / 読み込み完了処理
+│       └── SoundLoadUseCase.ts       # External sound loading / 外部サウンドの読み込み
+│
+├── SoundMixer.ts                     # Global sound controller / グローバルサウンドコントローラー
+├── SoundMixer/
+│   └── service/                      # SoundMixer services / SoundMixerサービス
+│       ├── SoundMixerStopAllService.ts # Stop all sounds / 全サウンド停止
+│       └── SoundMixerUpdateVolumeService.ts # Update global volume / グローバル音量更新
+│
+├── SoundTransform.ts                 # Volume and loop properties / 音量とループのプロパティ
+│
+├── Video.ts                          # Video class for video playback / 動画再生用のVideoクラス
+├── Video/
+│   ├── service/                      # Video-related services / Video関連のサービス
+│   │   ├── VideoApplyChangesService.ts # Apply video state changes / 動画状態変更の適用
+│   │   ├── VideoCreateElementService.ts # Create video element / 動画要素の作成
+│   │   ├── VideoEndedEventService.ts # Video ended event / 動画終了イベント
+│   │   ├── VideoLoadedmetadataEventService.ts # Metadata loaded event / メタデータ読み込みイベント
+│   │   └── VideoProgressEventService.ts # Video progress event / 動画進捗イベント
+│   └── usecase/                      # Video use cases / Videoユースケース
+│       ├── VideoBuildFromCharacterUseCase.ts # Build from character / キャラクターからの構築
+│       ├── VideoCanplaythroughEventUseCase.ts # Can play through event / 再生可能イベント
+│       ├── VideoPlayEventUseCase.ts  # Play event handling / 再生イベント処理
+│       └── VideoRegisterEventUseCase.ts # Register video events / 動画イベント登録
+│
+├── MediaUtil.ts                      # Utility functions for media / メディア用ユーティリティ関数
+│                                     # - AudioContext management / AudioContext管理
+│                                     # - Volume control / 音量制御
+│                                     # - Playing sounds/videos tracking / 再生中サウンド/動画の追跡
+│                                     # - AJAX helper / AJAXヘルパー
+│
+└── interface/                        # TypeScript interfaces / TypeScript インターフェース
+    ├── ISoundCharacter.ts            # Sound character definition / サウンドキャラクター定義
+    ├── IVideoCharacter.ts            # Video character definition / 動画キャラクター定義
+    ├── IAjaxOption.ts                # AJAX options / AJAXオプション
+    ├── IAjaxEvent.ts                 # AJAX events / AJAXイベント
+    ├── IURLRequestMethod.ts          # URL request methods / URLリクエストメソッド
+    ├── IURLRequestHeader.ts          # URL request headers / URLリクエストヘッダー
+    ├── IURLLoaderDataFormat.ts       # URL loader data format / URLローダーデータフォーマット
+    ├── IBlendMode.ts                 # Blend mode types / ブレンドモード型
+    ├── IBounds.ts                    # Bounds interface / バウンズインターフェース
+    ├── ICharacter.ts                 # Character interface / キャラクターインターフェース
+    ├── IDictionaryTag.ts             # Dictionary tag interface / 辞書タグインターフェース
+    ├── IFilterArray.ts               # Filter array interface / フィルター配列インターフェース
+    ├── IGrid.ts                      # Grid interface / グリッドインターフェース
+    ├── ILoopConfig.ts                # Loop config interface / ループ設定インターフェース
+    ├── ILoopType.ts                  # Loop type interface / ループタイプインターフェース
+    ├── IMovieClipActionObject.ts     # MovieClip action object / MovieClipアクションオブジェクト
+    ├── IMovieClipCharacter.ts        # MovieClip character / MovieClipキャラクター
+    ├── IMovieClipLabelObject.ts      # MovieClip label object / MovieClipラベルオブジェクト
+    ├── IMovieClipSoundObject.ts      # MovieClip sound object / MovieClipサウンドオブジェクト
+    ├── IPlaceObject.ts               # Place object interface / 配置オブジェクトインターフェース
+    ├── IShapeCharacter.ts            # Shape character / Shapeキャラクター
+    ├── ISoundTag.ts                  # Sound tag interface / サウンドタグインターフェース
+    ├── ISurfaceFilter.ts             # Surface filter interface / サーフェスフィルターインターフェース
+    ├── ITextFieldCharacter.ts        # TextField character / TextFieldキャラクター
+    ├── ITextFieldType.ts             # TextField type / TextFieldタイプ
+    └── ITextFormatAlign.ts           # TextFormat align / TextFormat配置
+```
+
+## API Overview / API概要
+
+### Sound Class / Soundクラス
+
+```typescript
+import { Sound } from "@next2d/media";
+import { URLRequest } from "@next2d/net";
+
+const sound = new Sound();
+sound.volume = 0.8;
+sound.loopCount = 3; // Loop 3 times / 3回ループ
+
+// Load external MP3 / 外部MP3を読み込み
+await sound.load(new URLRequest("path/to/audio.mp3"));
+
+// Play sound / サウンドを再生
+sound.play();
+
+// Stop sound / サウンドを停止
+sound.stop();
+```
+
+### SoundMixer Class / SoundMixerクラス
+
+```typescript
+import { SoundMixer } from "@next2d/media";
+
+// Global volume control (0.0 - 1.0) / グローバル音量制御 (0.0 - 1.0)
+SoundMixer.volume = 0.5;
+
+// Stop all playing sounds and videos / 全ての再生中サウンドと動画を停止
+SoundMixer.stopAll();
+```
+
+### Video Class / Videoクラス
+
+```typescript
+import { Video } from "@next2d/media";
+
+const video = new Video(640, 480);
+video.smoothing = true;
+video.loop = true;
+video.autoPlay = true;
+video.volume = 0.8;
+
+// Set video source / 動画ソースを設定
+video.src = "path/to/video.mp4";
+
+// Play video / 動画を再生
+await video.play();
+
+// Pause video / 動画を一時停止
+video.pause();
+
+// Seek to position / 位置をシーク
+video.seek(5.0); // Seek to 5 seconds / 5秒の位置にシーク
 ```
-npm install @next2d/renderer
+
+### SoundTransform Class / SoundTransformクラス
+
+```typescript
+import { SoundTransform } from "@next2d/media";
+
+const transform = new SoundTransform(0.8, 2);
+// volume: 0.8, loopCount: 2
 ```
 
+## Sound Loading and Playback Flow / サウンド読み込みと再生フロー
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Sound
+    participant SoundLoadUseCase
+    participant MediaUtil
+    participant SoundLoadEndEventUseCase
+    participant SoundDecodeService
+    participant AudioContext
+
+    User->>Sound: load(request)
+    Sound->>SoundLoadUseCase: execute(sound, request)
+    SoundLoadUseCase->>MediaUtil: $ajax(options)
+    MediaUtil->>MediaUtil: XMLHttpRequest
+
+    Note over MediaUtil: loadstart event
+    MediaUtil-->>Sound: SoundLoadStartEventService
+
+    Note over MediaUtil: progress event
+    MediaUtil-->>Sound: SoundProgressEventService
+
+    Note over MediaUtil: loadend event
+    MediaUtil->>SoundLoadEndEventUseCase: execute(sound, event)
+    SoundLoadEndEventUseCase->>SoundDecodeService: execute(arrayBuffer)
+    SoundDecodeService->>AudioContext: decodeAudioData(arrayBuffer)
+    AudioContext-->>SoundDecodeService: AudioBuffer
+    SoundDecodeService-->>SoundLoadEndEventUseCase: AudioBuffer
+    SoundLoadEndEventUseCase->>Sound: audioBuffer = result
+    SoundLoadEndEventUseCase-->>Sound: Dispatch COMPLETE event
+    Sound-->>User: Load completed
+
+    User->>Sound: play(startTime)
+    Sound->>MediaUtil: $getAudioContext()
+    MediaUtil-->>Sound: AudioContext
+    Sound->>AudioContext: createGain()
+    AudioContext-->>Sound: GainNode
+    Sound->>AudioContext: createBufferSource()
+    AudioContext-->>Sound: AudioBufferSourceNode
+    Sound->>Sound: Setup source & gain
+    Sound->>AudioBufferSourceNode: start(startTime)
+
+    Note over AudioBufferSourceNode: Playback in progress
+
+    AudioBufferSourceNode-->>Sound: ended event
+    Sound->>Sound: SoundEndedEventService
+
+    alt canLoop is true
+        Sound->>Sound: play() again
+    else
+        Sound->>Sound: stop()
+    end
+```
+
+## Video Rendering Pipeline / 動画レンダリングパイプライン
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Video
+    participant VideoCreateElementService
+    participant VideoRegisterEventUseCase
+    participant HTMLVideoElement
+    participant VideoPlayEventUseCase
+    participant OffscreenCanvas
+    participant VideoApplyChangesService
+
+    User->>Video: new Video(width, height)
+    User->>Video: src = "video.mp4"
+    Video->>VideoCreateElementService: execute()
+    VideoCreateElementService-->>Video: HTMLVideoElement
+    Video->>VideoRegisterEventUseCase: execute(videoElement, video)
+
+    VideoRegisterEventUseCase->>HTMLVideoElement: addEventListener("loadedmetadata")
+    VideoRegisterEventUseCase->>HTMLVideoElement: addEventListener("canplaythrough")
+    VideoRegisterEventUseCase->>HTMLVideoElement: addEventListener("progress")
+    VideoRegisterEventUseCase->>HTMLVideoElement: addEventListener("ended")
+
+    Video->>HTMLVideoElement: src = url
+    Video->>HTMLVideoElement: load()
+
+    HTMLVideoElement-->>Video: loadedmetadata event
+    Note over Video: VideoLoadedmetadataEventService
+    Video->>Video: Create OffscreenCanvas
+    Video->>Video: Get 2D context
+    Video->>Video: loaded = true
+
+    HTMLVideoElement-->>Video: canplaythrough event
+    Note over Video: VideoCanplaythroughEventUseCase
+
+    alt autoPlay is true
+        Video->>Video: play()
+    end
+
+    User->>Video: play()
+    Video->>HTMLVideoElement: play()
+    Video->>VideoPlayEventUseCase: execute(video)
+
+    loop Animation frame loop
+        VideoPlayEventUseCase->>VideoPlayEventUseCase: requestAnimationFrame
+        VideoPlayEventUseCase->>VideoApplyChangesService: execute(video)
+        VideoApplyChangesService->>Video: Update currentTime
+        VideoApplyChangesService-->>Video: Dispatch UPDATE event
+        VideoPlayEventUseCase->>OffscreenCanvas: drawImage(videoElement)
+        Note over OffscreenCanvas: Render current frame
+    end
+
+    HTMLVideoElement-->>Video: ended event
+    Note over Video: VideoEndedEventService
+    Video-->>Video: Dispatch ENDED event
+
+    alt loop is true
+        Video->>Video: currentTime = 0
+        Video->>Video: play()
+    else
+        Video->>Video: ended = true
+        Video->>Video: pause()
+    end
+
+    User->>Video: pause()
+    Video->>HTMLVideoElement: pause()
+    Video->>VideoPlayEventUseCase: cancelAnimationFrame
+    Video-->>Video: Dispatch PAUSE event
+```
+
+## Key Components / 主要コンポーネント
+
+### MediaUtil.ts
+
+Provides core utility functions for media handling:
+メディア処理のためのコアユーティリティ関数を提供します:
+
+- **AudioContext Management / AudioContext管理**: `$getAudioContext()`, `$bootAudioContext()`
+- **Volume Control / 音量制御**: `$getVolume()`, `$setVolume()`
+- **Playing Media Tracking / 再生中メディア追跡**: `$getPlayingSounds()`, `$getPlayingVideos()`
+- **AJAX Helper / AJAXヘルパー**: `$ajax()` for loading external resources / 外部リソース読み込み用
+- **Utility Functions / ユーティリティ関数**: `$clamp()` for value range limiting / 値の範囲制限用
+
+### Service Layer / サービス層
+
+Services handle specific operations and events:
+サービスは特定の操作とイベントを処理します:
+
+- **Sound Services**: Decoding, event handling (loadstart, progress, ended)
+  - **Soundサービス**: デコード、イベント処理 (loadstart, progress, ended)
+- **SoundMixer Services**: Global volume updates, stop all functionality
+  - **SoundMixerサービス**: グローバル音量更新、全停止機能
+- **Video Services**: Element creation, state changes, event handling
+  - **Videoサービス**: 要素作成、状態変更、イベント処理
+
+### Use Case Layer / ユースケース層
+
+Use cases orchestrate complex workflows:
+ユースケースは複雑なワークフローを調整します:
+
+- **Sound Use Cases**: Loading external audio, building from character data, load completion
+  - **Soundユースケース**: 外部音声読み込み、キャラクターデータからの構築、読み込み完了
+- **Video Use Cases**: Event registration, playback management, character building
+  - **Videoユースケース**: イベント登録、再生管理、キャラクター構築
+
+## Architecture / アーキテクチャ
+
+This package follows a clean architecture pattern:
+このパッケージはクリーンアーキテクチャパターンに従っています:
+
+1. **Domain Layer**: Core classes (`Sound`, `Video`, `SoundMixer`, `SoundTransform`)
+   - **ドメイン層**: コアクラス (`Sound`, `Video`, `SoundMixer`, `SoundTransform`)
+
+2. **Use Case Layer**: Business logic orchestration (`usecase/` folders)
+   - **ユースケース層**: ビジネスロジックの調整 (`usecase/` フォルダ)
+
+3. **Service Layer**: Specific operations and event handling (`service/` folders)
+   - **サービス層**: 特定の操作とイベント処理 (`service/` フォルダ)
+
+4. **Utility Layer**: Shared utilities (`MediaUtil.ts`)
+   - **ユーティリティ層**: 共有ユーティリティ (`MediaUtil.ts`)
+
+5. **Interface Layer**: TypeScript type definitions (`interface/` folder)
+   - **インターフェース層**: TypeScript型定義 (`interface/` フォルダ)
+
+## Browser Compatibility / ブラウザ互換性
+
+This package requires:
+このパッケージには以下が必要です:
+
+- Web Audio API support / Web Audio APIサポート
+- HTML5 Video support / HTML5 Videoサポート
+- OffscreenCanvas support (for Video) / OffscreenCanvasサポート (Video用)
+- XMLHttpRequest / ArrayBuffer support / XMLHttpRequest / ArrayBufferサポート
+
 ## License
+
 This project is licensed under the [MIT License](https://opensource.org/licenses/MIT) - see the [LICENSE](LICENSE) file for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next2d/media",
-  "version": "2.13.1",
+  "version": "3.0.1",
   "description": "Next2D Media Package",
   "author": "Toshiyuki Ienaga<ienaga@next2d.app> (https://github.com/ienaga/)",
   "license": "MIT",
@@ -24,9 +24,9 @@
     "url": "git+https://github.com/Next2D/Player.git"
   },
   "dependencies": {
-    "@next2d/events": "2.13.1",
-    "@next2d/net": "2.13.1",
-    "@next2d/display": "2.13.1",
-    "@next2d/geom": "2.13.1"
+    "@next2d/events": "3.0.1",
+    "@next2d/net": "3.0.1",
+    "@next2d/display": "3.0.1",
+    "@next2d/geom": "3.0.1"
   }
 }

package/src/Video/usecase/VideoPlayEventUseCase.js

@@ -22,9 +22,6 @@ export const execute = (video) => {
     if (playingVideos.indexOf(video) === -1) {
         playingVideos.push(video);
     }
-    if (video.$context && video.$videoElement) {
-        video.$context.drawImage(video.$videoElement, 0, 0, video.videoWidth, video.videoHeight);
-    }
     return requestAnimationFrame(() => {
         execute(video);
     });