311 lines
8.9 KiB
ReStructuredText
311 lines
8.9 KiB
ReStructuredText
.. include:: common.txt
|
|
|
|
:mod:`pygame.cdrom`
|
|
===================
|
|
|
|
.. module:: pygame.cdrom
|
|
:synopsis: pygame module for audio cdrom control
|
|
|
|
| :sl:`pygame module for audio cdrom control`
|
|
|
|
.. warning::
|
|
This module is non functional in pygame 2.0 and above, unless you have manually compiled pygame with SDL1.
|
|
This module will not be supported in the future.
|
|
One alternative for python cdrom functionality is `pycdio <https://pypi.org/project/pycdio/>`_.
|
|
|
|
The cdrom module manages the ``CD`` and ``DVD`` drives on a computer. It can
|
|
also control the playback of audio CDs. This module needs to be initialized
|
|
before it can do anything. Each ``CD`` object you create represents a cdrom
|
|
drive and must also be initialized individually before it can do most things.
|
|
|
|
.. function:: init
|
|
|
|
| :sl:`initialize the cdrom module`
|
|
| :sg:`init() -> None`
|
|
|
|
Initialize the cdrom module. This will scan the system for all ``CD``
|
|
devices. The module must be initialized before any other functions will
|
|
work. This automatically happens when you call ``pygame.init()``.
|
|
|
|
It is safe to call this function more than once.
|
|
|
|
.. ## pygame.cdrom.init ##
|
|
|
|
.. function:: quit
|
|
|
|
| :sl:`uninitialize the cdrom module`
|
|
| :sg:`quit() -> None`
|
|
|
|
Uninitialize the cdrom module. After you call this any existing ``CD``
|
|
objects will no longer work.
|
|
|
|
It is safe to call this function more than once.
|
|
|
|
.. ## pygame.cdrom.quit ##
|
|
|
|
.. function:: get_init
|
|
|
|
| :sl:`true if the cdrom module is initialized`
|
|
| :sg:`get_init() -> bool`
|
|
|
|
Test if the cdrom module is initialized or not. This is different than the
|
|
``CD.init()`` since each drive must also be initialized individually.
|
|
|
|
.. ## pygame.cdrom.get_init ##
|
|
|
|
.. function:: get_count
|
|
|
|
| :sl:`number of cd drives on the system`
|
|
| :sg:`get_count() -> count`
|
|
|
|
Return the number of cd drives on the system. When you create ``CD`` objects
|
|
you need to pass an integer id that must be lower than this count. The count
|
|
will be 0 if there are no drives on the system.
|
|
|
|
.. ## pygame.cdrom.get_count ##
|
|
|
|
.. class:: CD
|
|
|
|
| :sl:`class to manage a cdrom drive`
|
|
| :sg:`CD(id) -> CD`
|
|
|
|
You can create a ``CD`` object for each cdrom on the system. Use
|
|
``pygame.cdrom.get_count()`` to determine how many drives actually exist.
|
|
The id argument is an integer of the drive, starting at zero.
|
|
|
|
The ``CD`` object is not initialized, you can only call ``CD.get_id()`` and
|
|
``CD.get_name()`` on an uninitialized drive.
|
|
|
|
It is safe to create multiple ``CD`` objects for the same drive, they will
|
|
all cooperate normally.
|
|
|
|
.. method:: init
|
|
|
|
| :sl:`initialize a cdrom drive for use`
|
|
| :sg:`init() -> None`
|
|
|
|
Initialize the cdrom drive for use. The drive must be initialized for
|
|
most ``CD`` methods to work. Even if the rest of pygame has been
|
|
initialized.
|
|
|
|
There may be a brief pause while the drive is initialized. Avoid
|
|
``CD.init()`` if the program should not stop for a second or two.
|
|
|
|
.. ## CD.init ##
|
|
|
|
.. method:: quit
|
|
|
|
| :sl:`uninitialize a cdrom drive for use`
|
|
| :sg:`quit() -> None`
|
|
|
|
Uninitialize a drive for use. Call this when your program will not be
|
|
accessing the drive for awhile.
|
|
|
|
.. ## CD.quit ##
|
|
|
|
.. method:: get_init
|
|
|
|
| :sl:`true if this cd device initialized`
|
|
| :sg:`get_init() -> bool`
|
|
|
|
Test if this ``CDROM`` device is initialized. This is different than the
|
|
``pygame.cdrom.init()`` since each drive must also be initialized
|
|
individually.
|
|
|
|
.. ## CD.get_init ##
|
|
|
|
.. method:: play
|
|
|
|
| :sl:`start playing audio`
|
|
| :sg:`play(track, start=None, end=None) -> None`
|
|
|
|
Playback audio from an audio cdrom in the drive. Besides the track number
|
|
argument, you can also pass a starting and ending time for playback. The
|
|
start and end time are in seconds, and can limit the section of an audio
|
|
track played.
|
|
|
|
If you pass a start time but no end, the audio will play to the end of
|
|
the track. If you pass a start time and 'None' for the end time, the
|
|
audio will play to the end of the entire disc.
|
|
|
|
See the ``CD.get_numtracks()`` and ``CD.get_track_audio()`` to find
|
|
tracks to playback.
|
|
|
|
Note, track 0 is the first track on the ``CD``. Track numbers start at
|
|
zero.
|
|
|
|
.. ## CD.play ##
|
|
|
|
.. method:: stop
|
|
|
|
| :sl:`stop audio playback`
|
|
| :sg:`stop() -> None`
|
|
|
|
Stops playback of audio from the cdrom. This will also lose the current
|
|
playback position. This method does nothing if the drive isn't already
|
|
playing audio.
|
|
|
|
.. ## CD.stop ##
|
|
|
|
.. method:: pause
|
|
|
|
| :sl:`temporarily stop audio playback`
|
|
| :sg:`pause() -> None`
|
|
|
|
Temporarily stop audio playback on the ``CD``. The playback can be
|
|
resumed at the same point with the ``CD.resume()`` method. If the ``CD``
|
|
is not playing this method does nothing.
|
|
|
|
Note, track 0 is the first track on the ``CD``. Track numbers start at
|
|
zero.
|
|
|
|
.. ## CD.pause ##
|
|
|
|
.. method:: resume
|
|
|
|
| :sl:`unpause audio playback`
|
|
| :sg:`resume() -> None`
|
|
|
|
Unpause a paused ``CD``. If the ``CD`` is not paused or already playing,
|
|
this method does nothing.
|
|
|
|
.. ## CD.resume ##
|
|
|
|
.. method:: eject
|
|
|
|
| :sl:`eject or open the cdrom drive`
|
|
| :sg:`eject() -> None`
|
|
|
|
This will open the cdrom drive and eject the cdrom. If the drive is
|
|
playing or paused it will be stopped.
|
|
|
|
.. ## CD.eject ##
|
|
|
|
.. method:: get_id
|
|
|
|
| :sl:`the index of the cdrom drive`
|
|
| :sg:`get_id() -> id`
|
|
|
|
Returns the integer id that was used to create the ``CD`` instance. This
|
|
method can work on an uninitialized ``CD``.
|
|
|
|
.. ## CD.get_id ##
|
|
|
|
.. method:: get_name
|
|
|
|
| :sl:`the system name of the cdrom drive`
|
|
| :sg:`get_name() -> name`
|
|
|
|
Return the string name of the drive. This is the system name used to
|
|
represent the drive. It is often the drive letter or device name. This
|
|
method can work on an uninitialized ``CD``.
|
|
|
|
.. ## CD.get_name ##
|
|
|
|
.. method:: get_busy
|
|
|
|
| :sl:`true if the drive is playing audio`
|
|
| :sg:`get_busy() -> bool`
|
|
|
|
Returns True if the drive busy playing back audio.
|
|
|
|
.. ## CD.get_busy ##
|
|
|
|
.. method:: get_paused
|
|
|
|
| :sl:`true if the drive is paused`
|
|
| :sg:`get_paused() -> bool`
|
|
|
|
Returns True if the drive is currently paused.
|
|
|
|
.. ## CD.get_paused ##
|
|
|
|
.. method:: get_current
|
|
|
|
| :sl:`the current audio playback position`
|
|
| :sg:`get_current() -> track, seconds`
|
|
|
|
Returns both the current track and time of that track. This method works
|
|
when the drive is either playing or paused.
|
|
|
|
Note, track 0 is the first track on the ``CD``. Track numbers start at
|
|
zero.
|
|
|
|
.. ## CD.get_current ##
|
|
|
|
.. method:: get_empty
|
|
|
|
| :sl:`False if a cdrom is in the drive`
|
|
| :sg:`get_empty() -> bool`
|
|
|
|
Return False if there is a cdrom currently in the drive. If the drive is
|
|
empty this will return True.
|
|
|
|
.. ## CD.get_empty ##
|
|
|
|
.. method:: get_numtracks
|
|
|
|
| :sl:`the number of tracks on the cdrom`
|
|
| :sg:`get_numtracks() -> count`
|
|
|
|
Return the number of tracks on the cdrom in the drive. This will return
|
|
zero of the drive is empty or has no tracks.
|
|
|
|
.. ## CD.get_numtracks ##
|
|
|
|
.. method:: get_track_audio
|
|
|
|
| :sl:`true if the cdrom track has audio data`
|
|
| :sg:`get_track_audio(track) -> bool`
|
|
|
|
Determine if a track on a cdrom contains audio data. You can also call
|
|
``CD.num_tracks()`` and ``CD.get_all()`` to determine more information
|
|
about the cdrom.
|
|
|
|
Note, track 0 is the first track on the ``CD``. Track numbers start at
|
|
zero.
|
|
|
|
.. ## CD.get_track_audio ##
|
|
|
|
.. method:: get_all
|
|
|
|
| :sl:`get all track information`
|
|
| :sg:`get_all() -> [(audio, start, end, length), ...]`
|
|
|
|
Return a list with information for every track on the cdrom. The
|
|
information consists of a tuple with four values. The audio value is True
|
|
if the track contains audio data. The start, end, and length values are
|
|
floating point numbers in seconds. Start and end represent absolute times
|
|
on the entire disc.
|
|
|
|
.. ## CD.get_all ##
|
|
|
|
.. method:: get_track_start
|
|
|
|
| :sl:`start time of a cdrom track`
|
|
| :sg:`get_track_start(track) -> seconds`
|
|
|
|
Return the absolute time in seconds where at start of the cdrom track.
|
|
|
|
Note, track 0 is the first track on the ``CD``. Track numbers start at
|
|
zero.
|
|
|
|
.. ## CD.get_track_start ##
|
|
|
|
.. method:: get_track_length
|
|
|
|
| :sl:`length of a cdrom track`
|
|
| :sg:`get_track_length(track) -> seconds`
|
|
|
|
Return a floating point value in seconds of the length of the cdrom
|
|
track.
|
|
|
|
Note, track 0 is the first track on the ``CD``. Track numbers start at
|
|
zero.
|
|
|
|
.. ## CD.get_track_length ##
|
|
|
|
.. ## pygame.cdrom.CD ##
|
|
|
|
.. ## pygame.cdrom ##
|