
:mod:`cd` --- SGI システムの CD-ROM へのアクセス
================================================

.. module:: cd
   :platform: IRIX
   :synopsis: Silicon GraphicsシステムのCD-ROMへのインターフェース
   :deprecated:


.. deprecated:: 2.6
    :mod:`cd` モジュールは Python 3.0 での削除に向けて非推奨になりました。


このモジュールは Silicon Graphics CD ライブラリへのインターフェースを提供します。
Silicon Graphics システムだけで利用可能です。

ライブラリは以下のように使われます。

CD-ROM デバイスを :func:`open` で開き、 :func:`createparser` で CD から\
データをパースするためのパーザを作ります。
:func:`open` で返されるオブジェクトは CD からデータを読み込むのに使われますが、
CD-ROM デバイスのステータス情報や、CD の情報、たとえば目次などを得るのにも使われます。
CD から得たデータはパーザに渡され、パーザはフレームをパースし、あらかじめ加えられた\
コールバック関数を呼び出します。

オーディオCDはトラック :dfn:`tracks` あるいはプログラム :dfn:`programs`
(同じ意味で、どちらかの用語が使われます) に分けられます。
トラックはさらにインデックス :dfn:`indices` に分けられます。
オーディオ CD は、CD 上の各トラックのスタート位置を示す目次 :dfn:`table of contents`
を持っています。
インデックス0は普通、トラックの始まりの前のポーズです。
目次から得られるトラックのスタート位置は通常、インデックス1のスタート位置です。

CD 上の位置は2通りの方法で得ることができます。
それはフレームナンバーと、分、秒、フレームの3つの値からなるタプルの2つです。
ほとんどの関数は後者を使います。
位置はCDの開始位置とトラックの開始位置の両方に相対的になります。

モジュール :mod:`cd` は、以下の関数と定数を定義しています：


.. function:: createparser()

   不透明なパーザオブジェクトを作って返します。パーザオブジェクトのメソッドは下に記載されています。


.. function:: msftoframe(minutes, seconds, frames)

   絶対的なタイムコードである ``(minutes, seconds, frames)`` の3つ組の表現を、
   相当するCDのフレームナンバーに変換します。


.. function:: open([device[, mode]])

   CD-ROM デバイスを開きます。不透明なプレーヤーオブジェクトを返します；
   プレーヤーオブジェクトのメソッドは下に記載されています。
   デバイス *device* は SCSI デバイスファイルの名前で、例えば ``'/dev/scsi/sc0d4l0'``
   あるいは ``None`` です。
   もし省略したり、 ``None`` なら、ハードウエアが検索されて CD-ROM デバイスを\
   割り当てます。 *mode* は、省略しないなら ``'r'`` にすべきです。

このモジュールでは以下の変数を定義しています：


.. exception:: error

   様々なエラーについて発生する例外です。


.. data:: DATASIZE

   オーディオデータの1フレームのサイズです。
   これは ``audio`` タイプのコールバックへ渡されるオーディオデータのサイズです。


.. data:: BLOCKSIZE

   オーディオデータが読み取られていないフレーム1つのサイズです。

以下の変数は :func:`getstatus` で返されるステータス情報です：


.. data:: READY

   オーディオ CD がロードされて、ドライブが操作可能であることを示します。


.. data:: NODISC

   ドライブに CD がロードされていないことを示します。


.. data:: CDROM

   ドライブに CD-ROM がロードされていることを示します。
   続いて play あるいは read の操作をすると、I/O エラーを返します。


.. data:: ERROR

   ディスクや目次を読み込もうとしているときに起こるエラー。


.. data:: PLAYING

   ドライブがオーディオ CD を CD プレーヤーモードでオーディオ端子から再生\
   していることを示します。


.. data:: PAUSED

   ドライブが CD プレーヤーモードで、再生を一時停止していることを示します。


.. data:: STILL

   :const:`PAUSED` と同じですが、古いモデル（non 3301）である Toshiba CD-ROM
   ドライブのものです。このドライブはもうSGIから出荷されていません。


.. data:: audio
          pnum
          index
          ptime
          atime
          catalog
          ident
          control

   これらは整数の定数で、パーザのいろいろなタイプのコールバックを示していま\
   す。コールバックは CD パーザオブジェクトの :meth:`addcallback` で設定でき\
   ます（下記参照）。


.. _player-objects:

プレーヤーオブジェクト
----------------------

プレーヤーオブジェクト (:func:`open` で返されます) には以下のメソッドがあります：


.. method:: CD player.allowremoval()

   CD-ROM ドライブのイジェクトボタンのロックを解除して、ユーザが CD
   キャディを排出するのを許可します。


.. method:: CD player.bestreadsize()

   メソッド :meth:`readda` のパラメータ *num_frames* として最適の値を返します。
   最適値は CD-ROM ドライブからの連続したデータフローが許可される値が定義されます。


.. method:: CD player.close()

   プレーヤーオブジェクトと関連付けられたリソースを解放します。
   :meth:`close` を呼び出したあとでは、そのオブジェクトに対するメソッドは\
   使用できません。


.. method:: CD player.eject()

   CD-ROMドライブからキャディを排出します。


.. method:: CD player.getstatus()

   CD-ROMドライブの現在の状態に関する情報を返します。
   返される情報は以下の値からなるタプルです：
   *state* 、 *track* 、 *rtime* 、 *atime* 、 *ttime* 、
   *first* 、 *last* 、 *scsi_audio* 、 *cur_block* 。
   *rtime* は現在のトラックの初めからの相対的な時間；
   *atime* はディスクの初めからの相対的な時間；
   *ttime* はディスクの全時間です。
   それぞれの値の詳細については、マニュアルページ :manpage:`CDgetstatus(3dm)`
   を参照してください。
   *state* の値は以下のうちのどれか一つです：
   :const:`ERROR` 、 :const:`NODISC` 、 :const:`READY` 、
   :const:`PLAYING` 、 :const:`PAUSED` 、 :const:`STILL` 、 :const:`CDROM` 。


.. method:: CD player.gettrackinfo(track)

   特定のトラックについての情報を返します。
   返される情報は、トラックの開始時刻とトラックの時間の長さの二つの要素から\
   なるタプルです。


.. method:: CD player.msftoblock(min, sec, frame)

   分、秒、フレームの3つからなる絶対的なタイムコードを、与えられた CD-ROM
   ドライブの相当する論理ブロック番号に変換します。
   時刻を比較するには :meth:`msftoblock` よりも :func:`msftoframe`
   を使うべきです。論理ブロック番号は、CD-ROM ドライブによって必要とされる\
   オフセット値が違うため、フレームナンバーと異なります。


.. method:: CD player.play(start, play)

   CD-ROM ドライブのオーディオ CD の特定のトラックから再生を開始します。
   CD-ROM ドライブのヘッドフォン端子と（備えているなら）オーディオ端子から出\
   力されます。ディスクの最後で再生は停止します。
   *start* は再生を開始する CD のトラックナンバーです；
   *play* が0なら、CD は最初の一時停止状態になります。
   その状態からメソッド :meth:`togglepause` で再生を開始できます。


.. method:: CD player.playabs(minutes, seconds, frames, play)

   :meth:`play` と似ていますが、開始位置をトラックナンバーの代わりに分、\
   秒、フレームで与えます。


.. method:: CD player.playtrack(start, play)

   :meth:`play` と似ていますが、トラックの終わりで再生を停止します。


.. method:: CD player.playtrackabs(track, minutes, seconds, frames, play)

   :meth:`play` と似ていますが、指定した絶対的な時刻から再生を開始して、\
   指定したトラックで終了します。


.. method:: CD player.preventremoval()

   CD-ROM ドライブのイジェクトボタンをロックして、ユーザが CD キャディを\
   排出できないようにします。


.. method:: CD player.readda(num_frames)

   CD-ROM ドライブにマウントされたオーディオ CD から、指定したフレーム数を\
   読み込みます。オーディオフレームのデータを示す文字列を返します。
   この文字列はそのままパーザオブジェクトのメソッド :meth:`parseframe`
   へ渡すことができます。


.. method:: CD player.seek(minutes, seconds, frames)

   CD-ROM から次にデジタルオーディオデータを読み込む開始位置のポインタを設定します。
   ポインタは *minutes* 、 *seconds* 、 *frames* で指定した絶対的な\
   タイムコードの位置に設定されます。
   返される値はポインタが設定された論理ブロック番号です。


.. method:: CD player.seekblock(block)

   CD-ROM から次にデジタルオーディオデータを読み込む開始位置のポインタを設定します。
   ポインタは指定した論理ブロック番号に設定されます。
   返される値はポインタが設定された論理ブロック番号です。


.. method:: CD player.seektrack(track)

   CD-ROM から次にデジタルオーディオデータを読み込む開始位置のポインタを設定します。
   ポインタは指定したトラックに設定されます。
   返される値はポインタが設定された論理ブロック番号です。


.. method:: CD player.stop()

   現在実行中の再生を停止します。


.. method:: CD player.togglepause()

   再生中なら CD を一時停止し、一時停止中なら再生します。


.. _cd-parser-objects:

パーザオブジェクト
------------------

パーザオブジェクト (:func:`createparser` で返されます) には以下のメソッドがあります：


.. method:: CD parser.addcallback(type, func, arg)

   パーザにコールバックを加えます。
   デジタルオーディオストリームの8つの異なるデータタイプのためのコールバックを\
   パーザは持っています。
   これらのタイプのための定数は :mod:`cd` モジュールのレベルで定義されています
   (上記参照)。コールバックは以下のように呼び出されます：
   ``func(arg, type, data)`` 、ここで *arg* はユーザが与えた引数、
   *type* はコールバックの特定のタイプ、
   *data* はこの *type* のコールバックに渡されるデータです。
   データのタイプは以下のようにコールバックのタイプによって決まります：

   +-------------+--------------------------------------------------------------------------+
   | Type        | Value                                                                    |
   +=============+==========================================================================+
   | ``audio``   | :func:`al.writesamps` へそのまま渡すことのできる文字列。                 |
   +-------------+--------------------------------------------------------------------------+
   | ``pnum``    | プログラム（トラック）ナンバーを示す整数。                               |
   +-------------+--------------------------------------------------------------------------+
   | ``index``   | インデックスナンバーを示す整数。                                         |
   +-------------+--------------------------------------------------------------------------+
   | ``ptime``   | プログラムの時間を示す分、秒、フレームからなるタプル。                   |
   +-------------+--------------------------------------------------------------------------+
   | ``atime``   | 絶対的な時刻を示す分、秒、フレームからなるタプル。                       |
   +-------------+--------------------------------------------------------------------------+
   | ``catalog`` | CDのカタログナンバーを示す13文字の文字列。                               |
   +-------------+--------------------------------------------------------------------------+
   | ``ident``   | 録音のISRC識別番号を示す12文字の文字列。                                 |
   |             | 文字列は2文字の国別コード、3文字の所有者コード、2文字の年号、5文字のシリ |
   |             | アルナンバーからなります。                                               |
   +-------------+--------------------------------------------------------------------------+
   | ``control`` | CDのサブコードデータのコントロールビットを示す整数。                     |
   +-------------+--------------------------------------------------------------------------+


.. method:: CD parser.deleteparser()

   パーザを消去して、使用していたメモリを解放します。
   この呼び出しのあと、オブジェクトは使用できません。
   オブジェクトへの最後の参照が削除されると、自動的にこのメソッドが呼び出されます。


.. method:: CD parser.parseframe(frame)

   :meth:`readda` などから返されたデジタルオーディオ CD のデータの1つ\
   あるいはそれ以上のフレームをパースします。
   データ内にどういうサブコードがあるかを決定します。
   その前のフレームからサブコードが変化していたら、 :meth:`parseframe`
   は対応するタイプのコールバックを起動して、フレーム内のサブコードデータを\
   コールバックに渡します。
   C の関数とは違って、1つ以上のデジタルオーディオデータのフレームを\
   このメソッドに渡すことができます。


.. method:: CD parser.removecallback(type)

   指定した *type* のコールバックを削除します。


.. method:: CD parser.resetparser()

   サブコードを追跡しているパーザのフィールドをリセットして、初期状態にします。
   ディスクを交換したあと、 :meth:`resetparser` を呼び出さなければなりません。
