Developer Interface#

This part of the documentation covers all the interfaces of pydvdcss.

You interface with the underlying libdvdcss library using the DvdCss object.

class pydvdcss.DvdCss#

Python wrapper for VideoLAN’s libdvdcss. https://www.videolan.org/developers/libdvdcss.html

libdvdcss is part of the VideoLAN project, which among other things produces VLC, a full video client/server streaming solution. VLC can also be used as a standalone program to play video streams from a hard disk or a DVD.

The Environment Variables DVDCSS_METHOD and DVDCSS_VERBOSE are handled by set_cracking_mode() and set_verbosity() respectively. See those functions for more information.

libdvdcss is copyright VideoLAN

close() → bool#

Close the DVD by freeing the dvdcss memory and handle of the block device. It also clears the local data buffer.

This should always be run once you are finished with the opened disc, even if you don’t intend to open another disc in the same instance.

dispose() → None#

Closes any open disc and frees all data stored in this instance. It also unsets the libdvdcss verbosity and cracking mode.

This should be run when you intend to re-use the object for a new disc and want to start fresh.

If you simply want to open a new disc with the same settings and environment, run close() instead.

error() → str#

Returns the latest error that occurred in the given libdvdcss instance.

is_scrambled() → bool#

Check if the disc is scrambled.

open(psz_target: str) → int#

Open a DVD device or directory and return a dvdcss instance.

Initialize the libdvdcss library and open the requested DVD device or directory. libdvdcss checks whether ioctls can be performed on the disc, and when possible, the disc key is retrieved.

Parameters:

psz_target – A block device string, e.g. “E:”, “/dev/sr0”, an ISO image file, or a VOB/IFO structure directory.

Returns a handle to be used for all subsequent libdvdcss calls. If an error occurred, NULL is returned.

open_stream(p_stream: int, p_stream_cb: DvdCssStreamCb) → int#

Open a DVD device using custom read and seek functions.

Essentially instead of having libdvdcss read from a target device, you provide it functions that does the reading and seeking yourself.

Note: I have yet to actually get this to work. I don’t know if I’m doing something wrong in terms of ctypes definitions or something else, but the definitions seem correct. Perhaps p_stream is used in a way that I don’t yet understand.

Parameters:

  • p_stream – A private handle used by p_stream_cb.

  • p_stream_cb – A struct containing seek and read functions.

Returns a handle to be used for all subsequent libdvdcss calls. If an error occurred, NULL is returned.

read(i_blocks: int, i_flags: int = 0) → bytes#

Read from the disc and decrypt data if requested.

Parameters:

  • i_blocks – Number of logical blocks (2048*n) to read.

  • i_flags – NO_FLAGS by default, or you can specify the READ_DECRYPT flag.

Returns the read logical blocks, or raises an IOError if a reading error occurs.

seek(i_blocks: int, i_flags: int = 0) → int#

Seeks to the requested position of the disc, in logical blocks.

Parameters:

  • i_blocks – Position in logical blocks (2048*n) to seek to.

  • i_flags – NO_FLAGS by default, or you can specify SEEK_MPEG or SEEK_KEY flags.

Returns the new position in blocks, or a negative value if an error occurred.

  • Use SEEK_MPEG flag when seeking throughout VOB data sectors. It isn’t needed on the first sector.

  • Use SEEK_KEY flag the first time you enter a TITLE. You can always call it in VOB data sectors, however it will be unnecessary and cause slowdowns.

static set_cracking_mode(mode: Literal['unset', 'title', 'disc', 'key'] = 'key') → str | None#

Set libdvdcss cracking mode (DVDCSS_METHOD environment variable).

  • unset: Unset the DVDCSS_METHOD environment variable.

  • title: By default the decrypted title key is guessed from the encrypted sectors of the stream. Thus it should work with a file as well as the DVD device. But decrypting a title key may take too much time or even fail. With the title method, the key is only checked at the beginning of each title, so it will not work if the key changes in the middle of a title.

  • disc: The disc key is cracked first. Afterwards all title keys can be decrypted instantly, which allows checking them often.

  • key: The same as the “disc” method if you do not have a file with player keys at compile time. If you do, disc key decryption will be faster. This is the default method also employed by libdvdcss.

Returns the now current value of DVDCSS_METHOD, expected value should be the same as the mode string provided.

static set_verbosity(verbosity: int = 0) → int#

Set libdvdcss verbosity (DVDCSS_VERBOSE environment variable).

  • -1: Unset the DVDCSS_VERBOSE environment variable.

  • 0: No error messages, no debug messages (this is the default).

  • 1: Only error messages.

  • 2: Error and debug messages.

Returns the now current value of DVDCSS_VERBOSE, expected value should be the same as the verbosity int provided.