追記:以下で紹介している手法は古いAPIライブラリを使った方法です。現行ライブラリを使った手法は公式サイトをご確認下さい。
日本ではyoutubeに比べてマイナーな印象のあるVimeo。
しかし独自の規約により、クリエイター自身が高画質の動画を投稿していることが多く、玉石混淆なyoutubeよりも画質が良い傾向にあります。
また(今のところ)動画中の広告表示がないという利点もあります。
そんなvimeoにも開発者向けにプレイヤーAPIが提供されていますが、公式の説明ではいまいち分かりづらいと感じた点があったのと、まとまった解説をした記事等に出会わなかったので、自分なりに使い方をまとめてみました。
必要なもの
アカウント等は不要です。
公式のサンプルコードでは何の説明もなくjQueryを使っているのが気に食わないけど、jQueryは要りません。実際に必要なのはfroogaloop.jsというAPIアクセス用ライブラリだけです。(直接APIに触る方法もあるので、実はこれも必須ではないですが)
あと、iframe内をいじることになるため、クロスドメイン制約に引っかからないよう、テストの際は自前のサーバーもしくはオンラインエディタを使いましょう。
プレイヤーの準備
何はともあれ、まずライブラリの読み込み、そしてiframeで動画の埋め込みを行います。
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Vimeo playerAPI test</title>
</head>
<body>
<iframe id="player1" src="https://player.vimeo.com/video/50007657?api=1&player_id=player1" width="630" height="354" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
<script src="https://f.vimeocdn.com/js/froogaloop2.min.js"></script>
</body>
</html>
この時iframe要素のidと、srcのplayer_id=***のところを一致させるようにして下さい。
(oEmbedを経由して動画情報を取得する方法もありますが、今回は割愛します)
APIアクセスのための儀式
iframe要素を取得し、それをFroogaloop()という関数に渡すことで、対応するプレイヤーのAPIに触われるようになります。
<script src="https://f.vimeocdn.com/js/froogaloop2.min.js"></script>
<script>
var iframe = document.getElementById('player1');
var player = Froogaloop(iframe);
</script>
ちなみにFroogaloop()にはショートハンドがあり、
var player = $f(iframe);
とも書くことができます。(上記の公式サンプルコードではこちらが使われています。が、正直jQueryの"$"と紛らわしいのでサンプルでは使わない方がいい気が・・・)
本題 - プレイヤーの使い方について
プレイヤー側の準備が完了するとreadyというイベントが発火するので、それをイベントリスナでつかまえます。
addEvent()というFroogaloopオブジェクトのメソッドを使います。
var iframe = document.getElementById('player1');
var player = Froogaloop(iframe);
player.addEvent('ready', function(){
// ここに処理を書く
});
操作処理やイベントリスナの追加等は基本的にこのコールバック内に書くことが推奨されています。
プレイヤーに処理内容を伝えるには主にapi()というメソッドを使います。
以下、具体的な使い方です。
プレイヤー操作系
シンプルに処理内容を文字列で渡します。
// player.api('methodName');
// 再生
player.api('play');
// 一時停止
player.api('pause');
// プレイヤーを初期状態にもどす
player.api('unload');
使える処理は上記3つのみのようです。
シーク、setter系
第二引数にセットしたい値を渡します。
// player.api('methodName', value);
// 例:20秒地点にシーク
player.api('seekTo', 20);
// 例:音量を半分にする
player.api('setVolume', 0.5);
変わったところではインタフェース類の色を変えるsetColorなんてのがあります。
どういった処理が使えるかについてはこちらを参照。
getter系
コールバックで値を取得します。
ついでにプレイヤーのid名も取得できます。
// player.api('methodName', callback);
// 例:現在の再生位置を取得
player.api('getCurrentTime', function(value){
console.log(value); // [number]
});
// 例:一時停止状態かどうかを取得
// プレイヤーのidも取得できる
player.api('paused', function(value, id){
console.log(value, id); // [boolean] "'player1"
});
player.api('getCurrentTime') では返ってこないので注意。
使える処理の種類についてはsetter項のリンクを参照。
eventListener系
冒頭のreadyと同様にaddEvent()でイベントリスナを追加できます。逆にリスナを削除するときはremoveEvent()を使います。
// player.addEvent('eventName', callback);
// 例:動画が再生中のときに実行
// 発火する頻度は約0.25秒に一回程度
player.addEvent('playProgress', function(){
console.log("再生中!");
});
// 例:動画終了時に実行
// getter系と同様、プレイヤーのidも取得可能
player.addEvent('finish', function(id){
console.log(id + "の再生が終了しました!");
// リスナを削除するときはremoveEvent()
player.removeEvent('finish');
});
イベントの種類についてはこちらを参照。
また一部のイベントはdataオブジェクトを返します。
例えば動画ロード中に発火されるloadProgressイベントは
player.addEvent('loadProgress', function(data){
console.log(data); // Object {bytesLoaded: -1, bytesTotal: -1, percent: 0.012, duration: 144.911, seconds: 1.706}
});
と、ロードの進捗状況に関する情報を返してくれます。
これを利用することで、ある程度ロードが進んでから再生を開始させる、というようなことができます。
ただしロードは一度再生、もしくはシークしないと開始されませんので
- seekTo処理で適当な位置までシーク
- seekToで0に戻す
- シークすると同時に再生も始まってしまうのでpauseで止める
- 指定時間までロードが完了したら再生開始(&イベントリスナ削除)
という手順を踏む必要があります。
player.api('seekTo', 10); // 10秒後までシーク
player.api('seekTo', 0); // 0に戻す
player.api('pause'); // 再生させない
player.addEvent('loadProgress', function(data, player_id, event){
// 10秒地点までロードが完了したら再生開始
if (data.seconds > 10) {
player.api('play');
player.removeEvent('loadProgress'); // 再生が止められなくなるのでリスナは削除
}
});
ロードが遅くて途中で止まるということはあまりないとは思いますが一応・・・。
その他、分かったことがあれば随時追記していこうと思います。