:mod:`pygame2.sdl.cdrom` -- SDL CD-ROM management wrapper
=========================================================

The cdrom module manages the CD and DVD drives on a computer. It can
also control the playback of audio CDs.


.. module:: pygame2.sdl.cdrom
   :synopsis: SDL CD-ROM management wrapper

Module Functions
----------------
.. function:: get_name (index) -> str

  Gets the name of the specified CD- or DVD-ROM drive.

  Gets the system-dependent drive name (e.g. "/dev/cdrom" or "D:")
  for the CD- or DVD-Rom specified by the passed *index*.



.. function:: init () -> None

  Initializes the CD-ROM subsystem of the SDL library.


.. function:: num_drives () -> int

  Gets the number of accessible CD- and DVD-ROM drives for the system.



.. function:: quit () -> None

  Shuts down the CD-ROM subsystem of the SDL library.

  After calling this function, you should not invoke any class,
  method or function related to the CD-ROM subsystem as they are
  likely to fail or might give unpredictable results.



.. function:: was_init () -> bool

  Returns, whether the CD-ROM subsystem of the SDL library is initialized.



CD
--
.. class:: CD (index) -> CD

  Creates a new CD object for the CD- or DVD-ROM specified by the
  passed *index*. The *index* identifies the matching system CD/DVD-ROM
  number as returned by cdrom.num_drives ().

  The CD itself provides access to the track data on the CD/DVD,
  playing audio tracks, opening and closing the drive tray and so
  forth.


Attributes
^^^^^^^^^^
.. attribute:: CD.cur_frame

  The current frame offset within the curent track.

.. attribute:: CD.cur_track

  The current track.

.. attribute:: CD.index

  The drive index as specified in the constructor.

.. attribute:: CD.name

  The system-dependent drive name (e.g. "/dev/cdrom" or "D:").

.. attribute:: CD.num_tracks

  The total number of tracks on the CD or DVD.

.. attribute:: CD.status

  Gets the current CD status.

.. attribute:: CD.tracks

  Gets a list of :class:`CDTrack` objects with the CD track
  information.

Methods
^^^^^^^
.. method:: CD.close () -> None

  Releases the CD internals. Useful for e.g. switching CDs within
  the drive without the need to recreate the CD object. :meth:`open`
  will reinitialize the CD internals. You should not use any other
  method or attribute until a call to :meth:`open`.


.. method:: CD.eject () -> None

  Ejects the CD or DVD.

.. method:: CD.open () -> None

  (Re-)Opens the CD and initialises the CD internals
  after a :meth:`close` call.


.. method:: CD.pause () -> None

  Pauses the actual CD playback.


.. method:: CD.play (start, length[, asfps]) -> None

  Starts playing the current CD beginning at the give *start*
  time for a maximum of *length* seconds. The *start* and *length*
  arguments are handled as seconds by default. To use an exact frame
  offset instead ofseconds, pass True as third *asfps* parameter.


.. method:: CD.play_tracks ([starttrack, ntracks, start, length, asfps]) -> None

  Plays a certain number of tracks beginning at the passed start
  track. If *start* and *length* are not 0, *start* determines the
  offset of *starttrack* to begin the playback at and *length*
  specifies the amount of seconds to play from the last track
  within the track list. To use an exact frame offset instead of
  seconds for the *start* and *length* parameters, pass True as *asfps*
  parameter.


.. method:: CD.resume () -> None

  Resumes a previously paused playback.

.. method:: CD.stop () -> None

  Stops the current playback.

CDTrack
-------
.. class:: CDTrack() -> CDTrack

  The CDTrack class provides information about the track contents
  of a CD or DVD. It should not be created within user code.


Attributes
^^^^^^^^^^
.. attribute:: CDTrack.id

  Gets the CD track id.

.. attribute:: CDTrack.length

  Gets the track length in frames.

.. attribute:: CDTrack.minutes

  Gets the approximate track length in minutes.

.. attribute:: CDTrack.offset

  Gets the frame offset of the track on the CD.

.. attribute:: CDTrack.seconds

  Gets the approximate track length in seconds.

.. attribute:: CDTrack.time

  Gets the approximate track length in minutes and seconds as
  tuple.

.. attribute:: CDTrack.type

  Gets the track type (data or audio).


