----------------------------------------------------------------------- メディアプレーヤ連携プラグイン for Chararina 取扱説明書 Copyright(C) 2004-2005 Praesens, Inc. All rights reserved. http://www.praesens.co.jp/pws/ ----------------------------------------------------------------------- 1.はじめに メディアプレーヤ連携プラグインをダウンロードいただきありがとうご ざいます。 メディアプレーヤ連携プラグイン(以下本プラグイン)はChararina(キャラ リナ)上で動作するキャラクターと連動することが可能なプラグインです。 2,3章でキャラクターとの連携に用いるプラグイン関数の使用方法について 説明しますので、本プラグインに対応したキャラクターを作成する方はご 覧下さい。 なお、本プラグインの機能の利用には Windows Media Player 9 以降または iTunes 4.7以降がインストールされている必要があります。 2.プラグイン関数 本プラグインは非常駐プラグインです。キャラクターからLoadPlugin関 数を用いる必要があります。 メディアプレーヤ連携プラグインは綾織から呼び出せる下記のプラグイ ン関数を実装しています。キャラクターからこれらのプラグイン関数を呼 び出すことで、キャラクターからメディアプレーヤ・iTunesを操作できま す。 関数名の後の[WMP]はWindows Media Player対応、[iTunes]はiTunes対応を 表します。 import int LF_WMPP_SelectPlayer( string player ); [WMP][iTunes] [機能] 制御対象を指定する。 [引数] player: 制御対象。"WMP"ならWMPを、"iTunes"ならiTunesを制御します。 [戻り値] 0 成功 エラーならそれ以外を返します。 [補足] 起動直後はWMPを制御するモードになっています。 import int LF_WMPP_OpenItunes(); [iTunes] [機能] iTunesを開く。 [戻り値] 0 成功 エラーならそれ以外を返します。 import int LF_WMPP_GetItunesVersion( int &Major, int &Minor ); [iTunes] [機能] iTunesのバージョンを得る。 [引数] Major: メジャーバージョンを受け取る変数 Minor: マイナーバージョンを受け取る変数 [戻り値] 0 成功 エラーならそれ以外を返します。 import int LF_WMPP_GetCurrentSource( int &Source ); [iTunes] [機能] iTunesの現在選択中の曲のSource(*)を得る。 [引数] Source: Sourceを受け取る引数 [戻り値] 0 成功 エラーならそれ以外を返します。 import int LF_WMPP_GetItunesCdromPlaylistNames( string PlaylistNames[] ); [iTunes] [機能] 全CDドライブ内のCDのプレイリストを列挙する。 [引数] PlaylistNames: プレイリスト名を受け取る引数 [戻り値] 0 成功 エラーならそれ以外を返します。 import int LF_WMPP_PutItunesCdromPlaylist( int iPlaylist ); [iTunes] [機能] 指定したCDのプレイリストを現在のプレイリストにする。 [引数] iPlaylist: プレイリストを指定する変数 [戻り値] 0 成功 エラーならそれ以外を返します。 [補足] iPlaylistは、LF_WMPP_GetCdromPlaylistNames(PlaylistNames)実行後の 配列PlaylistNamesの添字に対応します。 import int LF_WMPP_GetItunesPlayState( int &state ); [iTunes] [機能] iTunesの再生状態を取得する。 [引数] state: 再生状態を受け取る変数。 [戻り値] 0 成功 エラーならそれ以外を返します。 [補足] 以下の状態があります。 0 停止状態 1 再生状態 2 早送り 3 巻き戻し import int LF_WMPP_GetWmppVersion( int &Major, int &Minor ); [WMP] [機能] Windows Media Player側Plugin(以下WMPP)のバージョンを得る。 [引数] Major: メジャーバージョンを受け取る変数 Minor: マイナーバージョンを受け取る変数 [戻り値] 0 成功 エラーならそれ以外を返します。 import int LF_WMPP_GetWmpVersion( int &Major, int &Minor ); [WMP] [機能] Windows Media Player(以下WMP)のバージョンを得る。 [引数] Major: メジャーバージョンを受け取る変数 Minor: マイナーバージョンを受け取る変数 [戻り値] 0 成功 エラーならそれ以外を返します。 import int LF_WMPP_GetCurrentMedia( string &MediaName ); [WMP][iTunes] [機能] 現在のメディアの名前を取得する。 [引数] MediaName: 現在のメディアの名前を受け取る変数 [戻り値] 0 成功 エラーならそれ以外を返します。 [補足] メディアがセットされていないときは、戻り値は0、MediaNameは空 文字列になります。 import int LF_WMPP_GetCurrentMediaAttributes( string AttributeNames[], string AttributeValues[] ); [WMP][iTunes] [機能] 現在のメディアの関連情報取得する。 [引数] AttributeNames: 取得すべき情報のAttribute名 AttributeValues: 取得した情報のAttribute値を受け取る変数 [戻り値] 0 成功 エラーならそれ以外を返します。 [補足] AttributeNamesにAttribute名をセットしてこの関数を呼ぶと、対応す るAttribute値がAttributeValuesに書き込まれます。 メディアがセットされていないときは、戻り値は0、AttributeValues は空文字列からなる配列になります。 WMPの場合は、以下のAttribute名が使用可能です。 よく使われるAttribute名: "Name" : タイトル("Title"でも同じ) "FileSize" : ファイルサイズ "FileType" : 3文字の拡張子(wmaやmp3など) "Duration" : 曲の秒数 "SourceURL": URL 利用可能なAttribute名の一覧は、以下のURLを参照してください(英語)。 http://msdn.microsoft.com/library/en-us/wmplay10/mmp_sdk/attributereference.asp iTunesで利用可能なAttribute名の一覧は、注1 を参照してください import int LF_WMPP_GetCurrentPlaylist( string Playlist[] ); [WMP][iTunes] [機能] 現在のプレイリストを取得する。 [引数] Playlist: 取得したプレイリストを受け取る変数 [戻り値] 0 成功 エラーならそれ以外を返します。 [補足] プレイリストがセットされていないときは、戻り値は0、Playlist は空文字列になります。 import int LF_WMPP_GetCurrentPlaylistItemAttributes( string AttributeNames[], string AttributeValues[][] ); [WMP][iTunes] [機能] 現在のプレイリストの各メディアアイテムの関連情報を取得する。 [引数] AttributeNames: 取得すべき情報のAttribute名 AttributeValues: 取得した情報のAttribute値を受け取る変数 [戻り値] 0 成功 エラーならそれ以外を返します。 [補足] プレイリストがセットされていないときは、戻り値は0、 AttributeValuesは空になります。 import int LF_WMPP_PlayFile( string Filename ); [WMP][iTunes](注3) [機能] ファイルを指定して再生する。 [引数] Filename: 再生すべきファイルのファイル名 [戻り値] 0 成功 エラーならそれ以外を返します。 import int LF_WMPP_Play(); [WMP][iTunes] import int LF_WMPP_Stop(); [WMP][iTunes] import int LF_WMPP_Next(); [WMP][iTunes] import int LF_WMPP_Prev(); [WMP][iTunes] import int LF_WMPP_Pause(); [WMP][iTunes] [機能] 再生/停止/次へ/前へ/一時停止 [引数] [戻り値] 0 成功 エラーならそれ以外を返します。 import int LF_WMPP_GetPlayState( int &state ); [WMP] [機能] 再生状態を取得する。 [引数] state: 再生状態を受け取る変数。 [戻り値] 0 成功 エラーならそれ以外を返します。 [補足] 以下の状態があります。 0 未知の状態 1 停止中 2 一時停止中 3 再生中 4 早送り中 5 巻き戻し中 6 バッファリング中 7 サーバの応答待ち中 8 メディアの末尾に達した 9 曲の切り替わり中 10 再生可能状態 11 再接続中 import int LF_WMPP_GetPosition( double &position ); [WMP][iTunes] [機能] 現在のメディアの再生位置(秒)を取得する。 [引数] position: 再生位置(秒)を受け取る変数 [戻り値] 0 成功 エラーならそれ以外を返します。 [補足] メディアがセットされていない場合は、戻り値は0、positionは0.0 になります。 iTunesの場合は、positionの精度は1秒です。 import int LF_WMPP_GetCdromDrives( string DriveName[] ); [WMP] [機能] CD/DVDドライブを列挙する。 [引数] DriveName: ドライブ名を受け取る変数 [補足] 例えばD,E,FドライブがCDドライブだった場合、 DriveName[0]に"D:"が DriveName[1]に"E:"が DriveName[2]に"F:"が それぞれ入ります [戻り値] 0 成功 エラーならそれ以外を返します。 import int LF_WMPP_PutCdromPlaylist( string DriveName ); [WMP] [機能] 再生すべきCDを指定する。 [引数] DriveName: ドライブ名(例 "D:") [戻り値] 0 成功 エラーならそれ以外を返します。 [補足] 指定したCDROMドライブのCDの全トラックからなるプレイリストを作 成し、それを現在のプレイリストにします。 import int LF_WMPP_PutUrl( string URL ); [WMP][iTunes](注3) [機能] 再生すべきクリップを指定する。 [引数] URL: URL [戻り値] 0 成功 エラーならそれ以外を返します。 [補足] WMPの場合: URLのプロトコルとして、file, http, wmpcd, wmpdvd などが指定可 能です。おそらく、拡張子.wplのファイルを指定してプレイリスト をセットすることが可能です。 file:// 例: "file://f:/mp3/ba_01.mp3" http:// 例: "http://www.praesens.co.jp/pws/service/voice/haruna1.wav" wmpcd://drive/track でCDの指定が可能。 例: "wmpcd://0/4" 注意: ドライブは0〜 トラックは1〜 数字で指定すること。トラッ クの省略は不可。 wmpdvd://drive/title/chapter?contentdir=path でDVDの指定が可能。 例: "wmpdvd://F" "wmpdvd://F/2" "wmpdvd://F/2/4" "wmpdvd://Z/2/4?contentdir="d:\sample1\video_ts" iTunesでは、以下のような制約があります. ・URLのプロトコルとしてhttpのみが使用可能です. ・wavファイルを再生できません. import int LF_WMPP_OpenWmp(); [WMP] [機能] WMPを起動する。 [引数] なし [戻り値] 0 成功 -14 WMP9以降がインストールされていない それ以外のエラーならそれ以外を返します。 import int LF_WMPP_GetCurrentMediaError( int &ErrorCode, string &ErrorString ); [WMP] [機能] プレイヤの現在のメディアのエラー情報を得る。 [引数] ErrorCode: エラーコードを受け取る変数 ErrorString: エラーを表す文字列を受け取る変数 [戻り値] 0 成功 それ以外のエラーならそれ以外を返します。 [補足] 現在のメディアにエラーが無い場合は、戻り値は0かつErrorCodeは0 になります。 import int LF_WMPP_GetPlaylistNames( string PlaylistNames[] ); [WMP][iTunes](注2) [機能] プレイリストコレクション内のプレイリストの名前一覧を得る [引数] PlaylistNames: プレイリスト名を受け取る変数 [戻り値] 0 成功 それ以外のエラーならそれ以外を返します。 import int LF_WMPP_GetPlaylistItemCount( int iPlaylist, int &count ); [WMP][iTunes](注2) [機能] プレイリストコレクション内の指定したプレイリストの曲数を得る [引数] iPlaylist: プレイリストを指定する変数. count: 曲数を受け取る変数 [戻り値] 0 成功 それ以外のエラーならそれ以外を返します。 [補足] iPlaylistは、LF_WMPP_GetPlaylistNames(PlaylistNames)実行後の 配列PlaylistNamesの添字に対応します。 import int LF_WMPP_PutPlaylist( int iPlaylist ); [WMP][iTunes](注2) [機能] プレイリストコレクション内の指定したプレイリストを、現在の プレイリストにする。 [引数] iPlaylist: プレイリストを指定する変数 [戻り値] 0 成功 それ以外のエラーならそれ以外を返します。 [補足] iPlaylistは、LF_WMPP_GetPlaylistNames(PlaylistNames)実行後の 配列PlaylistNamesの添字に対応します。 import int LF_WMPP_PutPlaylistFiles( string Filenames[] ); [WMP][iTunes](注3) [機能] プレイヤのプレイリストに複数のファイルをセットする。 [引数] Filenames: ファイル名を指定する変数 [戻り値] 0 成功 それ以外のエラーならそれ以外を返します。 ※よくあるエラーコード -1 WMPPが起動していない。あるいはWMPのバージョンが古い。 -3,-4 プラグインのバージョンが古い可能性があります -7 何らかのエラーです。 -14 WMP9以降がインストールされていない 注1: iTunesでは以下のAttributeNameのみ対応します。 WMP互換のもの: Title, Name, FileSize, Size, Duration, SourceURL, Artist, Author, Album, WM/AlbumTitle, Genre, WM/Genre, Composer, WM/Composer WMP非互換のもの: KindAsString (FileTypeの代わり) 注2: iTunesではPlaylistは以下の8つのSourceに分類されるが、ここではLibrary SoureのPlaylistのみを扱う。 - Library Source - iPod Source - Audio CD Source - MP3 CD Source - Device Source - Radio Source - Shared Library Source - Unknown Source 注3: iTunesでは新規に"Chararina Playlist"という名前のPlaylistを作成する。 3.コールバック関数 export void LF_WMPP_cNotify( int notify ); [WMP] 機能 WMPPのイベント発生時にコールバックされる。 引数 notify : イベントの種類。後述。 戻り値 なし 補足 以下のnotifyがあります。 WMPPの起動 notify = 2 WMPPの終了 notify = 3 再生 notify = 4 停止 notify = 5 一時停止 notify = 6 曲の末尾に達した notify = 7 曲の切り替わり notify = 8 複数のイベントが立て続けに発生した場合、後発のイベントを取りこ ぼす可能性があります。 例えばプレイリストのある曲の終わりに達し、次の曲の再生が始まっ た場合、 曲の末尾→曲の切り替わり→曲の再生 の3つのイベントが発生します が、曲の末尾のイベントしかとれない可能性があります。 export void LF_WMPP_cItunesNotify( int notify, string MediaName ); 機能 iTunesのイベント発生時にコールバックされる。 引数 notify : イベントの種類。後述。 MediaName : イベント発生時のメディア名 戻り値 なし 補足 以下のnotifyがあります。 Itunesの終了 notify = 3 再生・あるいは連続再生時に次の曲に移った notify = 4 停止・あるいは曲の終わりに達した notify = 5 ※ LF_WMPP_OpenItunesを予め呼んでおかないと、この関数は呼ばれません。 4.著作権、免責事項など 知的財産権 ・本ソフトウェア(画像・ドキュメントを含む)に関する一切の著作権その他 の無体財産権は、プラエセンス株式会社が所有します。 禁止事項 ・お客様は、本ソフトウェアについて、変更、改変、複製を行うことはでき ません。 ・お客様は、本ソフトウェアについて、リバースエンジニアリング、逆コン パイル・逆アセンブル、その他の方法でソースコードを解析することはで きません。また、本ソフトウェアが生成するデータファイルについて、リ バースエンジニアリングすることはできません。 免責事項 ・本ソフトウェアは現状のままで提供されるものであり、当社は、本ソフト ウェアに関して、完全性・正確性・有用性・第三者の権利不侵害性・その 他一切の保証を致しません。 ・当社は、本ソフトウェアの瑕疵、不具合等ならびに本ソフトウェアを使用 した結果および使用不可につき、修補義務・保守義務・その他いかなる責 任も負いません。 5. 変更履歴 2005/6/2 Ver 1.11 ・iTunesに対応 2004/7/13 Ver 1.10 (for Chararina 3.01) ・リソースの開放忘れを修正 2004/7/1 Ver 1.0 (for Chararina) ・Windows Media Playerへのプラグイン登録タイミングをプラグイン使用開 始時に変更 2004/6/16 Ver 1.0 (for Chararina) ・第1版完成