Mashup Award 9でGracenoteのAPIを使ってみよう

はじめに

Mashup Awards 9 (MA9)のAPI一覧にGracenoteのAPIがあったので（以前のMAにもあった気がするけど）何となくいじってみた。Gracenoteは音楽のメタデータを扱うサービス。iTunesでも使われている風。
基本的には以下のサイトに端的に書いてあるのでこれに従えば使えるのだけれど、いくつか補足なものも含めて記すなど。
GracenoteのAPIを試してみた - notes plastiques
なお、利用規約に明示されているが、一般に公開されているものは商用利用は不可なので注意。商用利用したい場合はGracenoteに連絡する必要がある。
※まあ、自分はMA9で使うかどうかわかんないけどねー。

注意

GracenoteのサイトのAPI周りのコンテンツはちょくちょくリンク切れしてるので日本語ページでリンク切れしているものは英語ページに行くとよい。
日本語版開発者サイトの最下部の右端に「English Site」とあるのでそこから辿れる。日本語に戻すときには同じところに「日本語」がある。

提供形態

Gracenote Developer Music + Auto APIs |
何はともあれ上記のページへ。上部にある「プラットフォーム」というリンクから「GNSDK」「Mobile Client」「Web API」の3種類の提供形態の説明に遷移できる。「はじめに」に書いた説明サイトでは主に「Web API」について記してある。

GNSDK: C言語ベースのライブラリ。ライブラリのアーカイブの中にサンプルなどもある。
Mobile Client: iOSとAndroid用のSDK。
Web API: Web経由で利用できるAPI。XMLをPOSTするとXMLで結果が返ってくる。上記2つとは異なりCDや音声認識でのルックアップはできない。

以下、できること一覧。

GNSDK
- アルバム名、アーティスト名、トラック名でのテキスト検索
- ローカルメディアライブラリを整理分類するためのフィンガープリント照合
- CD検索およびCD認識
Mobile Client
- アルバム名、アーティスト名、トラック名でのテキスト検索
- ローカルメディアライブラリを整理分類するためのフィンガープリント照合
- モバイル端末での音楽識別用ストリーミング・フィンガープリント
Web API
- アルバム名、アーティスト名、トラック名でのテキスト検索

1. 開発者登録

Gracenote Developer Music + Auto APIs |
上記ページの上部にある「register」というリンクから登録画面に行ける。名前とメールアドレスを入力するかfacebookアカウントで登録する。前者の場合はメールが届くのでその中にあるリンクからパスワード等の登録画面に遷移する。
以降はログインしているものとして説明する。

2. アプリ登録

開発者登録が完了してログイン後の画面に遷移すると、「APIキーの取得」「アプリの作成」「実行」の3段階の開発ステップについて記した画面と「Add a new app」というボタンがある。
このボタンを押して「App Name」を入力して「Create App」ボタンを押すと自分用のアプリが一個登録される。謎の「Platform」という選択項目があるものの一個しか選択できないので気にしない。
登録したアプリの名前はログイン後の一覧画面に表示され、それをクリックすると当該アプリでGracenoteにアクセスするための情報が表示される。
現時点では以下の項目が出てくる。

App Name: アプリケーションの名前。特に何という訳でもないらしい。
Client ID for Mobile Client, Web API, and eyeQ: クライアントID（Client ID）。「Web API」の場合は基本この項目だけ使う。「Mobile Client」も同じっぽい？
License information for GNSDK: クライアントID（Client ID）、クライアントタグ（Client Tag）、ライセンス文字列（License String）。「GNSDK」の場合はこちらの項目を使う。

3-1. Web API版アプリの作成

基本は「GracenoteのAPIを試してみた - notes plastiques」のやり方でOK。また、開発者サイトの「Web API」の説明ページにも類似の説明がある。
以下にcurlを使ってLinux上で実験する場合の一例だけざっくり記す。

クライアントIDのメモ

Gracenote開発者サイトにログインして「MyApps」の登録したアプリにあるクライアントID（「Client ID for Mobile Client, Web API, and eyeQ」の方）をメモする。

クライアントIDの登録とユーザIDの取得

以下の内容の「register.xml」的な名前のファイルを作成する。「client_id_string」にはメモしたクライアントIDを記す。

<QUERIES>
    <QUERY CMD="REGISTER">
        <CLIENT>client_id_string</CLIENT>
    </QUERY>
</QUERIES>

以下のようなコマンドを発行する。「XXX」にはクライアントIDのハイフンの左側を記す。たとえばクライアントIDが「123-456」なら「https://c123.web.cddbp.net/webapi/xml/1.0/」になる。

curl -d @register.xml https://cXXX.web.cddbp.net/webapi/xml/1.0/

以下のようなレスポンスが返ってくるので「user_id_string」をメモする。仮にこれを「ユーザID」と呼ぶ。

<RESPONSES>
 <RESPONSE STATUS="OK">
   <USER>user_id_string</USER>
 </RESPONSE>
<RESPONSES>

クエリの発行（ケース1：基本）

「request01.xml」的な名前のファイルに以下を記す。「client_id_string」「user_id_string」にはメモしたクライアントIDとユーザIDを記す。日本語の場合はに「jpn」と入れる。これらの定義はAPI仕様書に明記されている。また、ファイルの文字コードはUTF-8にする。

<QUERIES>
  <AUTH>
    <CLIENT>client_id_string</CLIENT>
    <USER>user_id_string</USER>
  </AUTH>
  <LANG>jpn</LANG>
  <QUERY CMD="ALBUM_SEARCH">
    <MODE>SINGLE_BEST</MODE>
    <TEXT TYPE="TRACK_TITLE">トキメクトキメケ</TEXT>
  </QUERY>
</QUERIES>

以下のようなコマンドを発行する。「XXX」にはクライアントIDのハイフンの左側を記す。たとえばクライアントIDが「123-456」なら「https://c123.web.cddbp.net/webapi/xml/1.0/」になる。

curl -d @request01.xml https://cXXX.web.cddbp.net/webapi/xml/1.0/

以下のようなレスポンスが返ってくる。やったね。ちなみに実際には「gracenote_id」の部分にちゃんとしたIDが入っている。

<RESPONSES>
 <RESPONSE STATUS="OK">
   <ALBUM>
      <GN_ID>gracenote_id1</GN_ID>
      <ARTIST>モーニング娘。</ARTIST>
      <TITLE>ブレインストーミング / 君さえ居れば何も要らない [初回盤D]</TITLE>
      <PKG_LANG>JPN</PKG_LANG>
      <DATE>2013</DATE>
      <GENRE NUM="61406" ID="25350">ポップ (日本)</GENRE>
      <MATCHED_TRACK_NUM>3</MATCHED_TRACK_NUM>
      <TRACK_COUNT>5</TRACK_COUNT>
      <TRACK>
         <TRACK_NUM>3</TRACK_NUM>
         <GN_ID>gracenote_id2</GN_ID>
         <ARTIST>道重さゆみ, 譜久村聖, 生田衣梨奈, 飯窪春菜, 石田亜佑美</ARTIST>
         <TITLE>トキメクトキメケ</TITLE>
      </TRACK>
   </ALBUM>
 </RESPONSE>
</RESPONSES>

クエリの発行（ケース2：拡張情報）

「request02.xml」的な名前のファイルに以下を記す。「client_id_string」「user_id_string」にはメモしたクライアントIDとユーザIDを記す。日本語の場合はに「jpn」と入れる。これらの定義はAPI仕様書に明記されている。また、ファイルの文字コードはUTF-8にする。

<QUERIES>
  <AUTH>
    <CLIENT>client_id_string</CLIENT>
    <USER>user_id_string</USER>
  </AUTH>
  <LANG>jpn</LANG>
  <QUERY CMD="ALBUM_SEARCH">
    <MODE>SINGLE_BEST</MODE>
    <TEXT TYPE="TRACK_TITLE">トキメクトキメケ</TEXT>
    <OPTION>
      <PARAMETER>SELECT_EXTENDED</PARAMETER>
      <VALUE>MOOD,TEMPO</VALUE>
    </OPTION>
    <OPTION>
      <PARAMETER>SELECT_DETAIL</PARAMETER>
      <VALUE>MOOD:2LEVEL,TEMPO:3LEVEL</VALUE>
    </OPTION>
  </QUERY>
</QUERIES>

以下のようなコマンドを発行する。「XXX」にはクライアントIDのハイフンの左側を記す。たとえばクライアントIDが「123-456」なら「https://c123.web.cddbp.net/webapi/xml/1.0/」になる。

curl -d @request02.xml https://cXXX.web.cddbp.net/webapi/xml/1.0/

以下のようなレスポンスが返ってくる。やったね。ちなみに実際には「gracenote_id1」「gracenote_id2」の部分にちゃんとしたIDが入っている。ケース1とは異なり2レベル分の「ムード」や3レベル分の「テンポ」の情報が含まれている。

<RESPONSES>
 <RESPONSE STATUS="OK">
   <ALBUM>
      <GN_ID>gracenote_id1</GN_ID>
      <ARTIST>モーニング娘。</ARTIST>
      <TITLE>ブレインストーミング / 君さえ居れば何も要らない [初回盤D]</TITLE>
      <PKG_LANG>JPN</PKG_LANG>
      <DATE>2013</DATE>
      <GENRE NUM="61406" ID="25350">ポップ (日本)</GENRE>
      <MATCHED_TRACK_NUM>3</MATCHED_TRACK_NUM>
      <TRACK_COUNT>5</TRACK_COUNT>
      <TRACK>
         <TRACK_NUM>3</TRACK_NUM>
         <GN_ID>gracenote_id2</GN_ID>
         <ARTIST>道重さゆみ, 譜久村聖, 生田衣梨奈, 飯窪春菜, 石田亜佑美</ARTIST>
         <TITLE>トキメクトキメケ</TITLE>
         <MOOD ORD="1" ID="42955">ソワソワ</MOOD>
         <MOOD ORD="2" ID="65350">ダーク / ポップ / テンション</MOOD>
         <TEMPO ORD="1" ID="43078">ファスト テンポ</TEMPO>
         <TEMPO ORD="2" ID="34292">速い</TEMPO>
         <TEMPO ORD="3" ID="34331">150台</TEMPO>
      </TRACK>
   </ALBUM>
 </RESPONSE>
</RESPONSES>

付記1

「ALBUM」の概念は日本の商用の概念の「アルバム」とは違うので注意。日本の商用の概念でいう「シングル」「アルバム」はどちらも「ALBUM」であり、その中の楽曲が「TRACK」として扱われる（「シングル」言うてもカップリングを含んだ複数の楽曲をまとめて収録したものだしね）。

付記2

ムードの「ソワソワ」とかテンポの「ファストテンポ」とか何だよという感じだが、ジャンルなども含めてこれらの一覧は「samples/code_snippets/list.c」で取れるっぽい（一部バグがあるのでこちらも参照）。「samples/code_snippets/list.c」には「samples/playlist」などの冒頭にある「#define GNSDK_PLAYLIST 1」などの記述が無いが、そのままだとデフォルトでこれら全部が定義されてる扱いになり、存在しないヘッダまでインクルードしにいってビルド時にエラーを吐くので、適当に定義してあげるかエラーのincludeを取り除くか、空のヘッダーファイルを作ってあげるのが吉。

3-2. GNSDK版アプリの作成（サンプルを動かすまで）

Gracenote開発者サイトからダウンロードできるGNSDKライブラリのアーカイブにはWindows上でVisualStudioやCygwin上でのやり方が書いてあるが、ここでは普通にgcc等が入ってるLinuxを前提として記す（特にCygwinと違いはないのだけれども）。

ライブラリアーカイブのダウンロード

Gracenote開発者サイトからライブラリやサンプルやビルド方法を記したアーカイブがダウンロードできるが、2013/09/30時点では日本語ページにある「GNSDK 3.2.0.422o (42 MB) Updated 01-08-2013」を落とそうとすると「 https://notarealurl.com/ 」に飛ばされる。何が「Not a real URL」だコノヤロウ。ということで、画面最下部の利用規約とかのリンクの横にある「English Site」から辿って英語版のGNSDKページに遷移する。と、いうか、要は「 https://developer.gracenote.com/gnsdk 」に行って最新のStable版をダウンロードする。ちなみに自分が落としたのは「GNSDK 3.02.0.422o Stable, Updated 01-08-2013 」。

wget https://gracenotedeveloper.s3.amazonaws.com/sdks/gnsdk/3.02.0.422o/gnsdk-3.02.0.422o-20130108.zip

アーカイブを適当に展開する。なお、最上位フォルダがないため変なところで展開すると散らばるので注意。展開用のフォルダ内でやると吉。
展開した後の「README_MSWindows.txt」「README_Samples.txt」にそれぞれWindowsベースでの使い方が書いてある。ここでは気にしないが読んでおくと吉。

クライアントID、クライアントタグ、ライセンス文字列のメモ

Gracenote開発者サイトにログインして「MyApps」の登録したアプリにあるクライアントID（Client ID）、クライアントタグ（Client Tag）、ライセンス文字列（License String）（「License information for GNSDK」の方）をメモする。

サンプルのビルド

展開した後のフォルダ「samples」の中にサンプルがある。
たとえば「samples/playlist」の中で「make」すると勝手に上位のライブラリやヘッダを読みこみつつビルドしてくれる。どのサンプルもビルド後の実行ファイルは「sample」。

ライセンスファイルの作成

メモしたライセンス文字列を適当なファイルに書いて保存する。ここでは仮に「samples/licfile.txt」とする。なお、文字列は「-- BEGIN LICENSE vX.Y xxx --」の行から始まり「-- END LICENSE xxx --」の行で終わる。この2つの行も含めること。改行なども除去せずにそのまま反映すること。

サンプルの実行

ビルド後の「samples/playlist」の中で以下を実行する。「client_id_string」「client_tag_string」にはメモしたクライアントIDとクライアントタグを記す。

./sample client_id_string client_tag_string ../licfile.txt

「samples/playlist」は初回は少し時間が掛るが、成功すればプレイリストがザーッと出てくる。