Device...Device(3pm)

💿 Device::Cdio::Device 💿

(straight from the User Contributed Perl Documentation, page Device...Device(3pm) — yes that's really the page name bestie, don't @ me)

okay so this class is literally THE one for all the disc-and-device stuff in Cdio. drives, discs, tracks, the whole vibe. slay. let's get into it 💅

---

🌸 NAME 🌸

Device::Cdio::Device — the class for disc and device aspects of Cdio. that's the whole assignment. iconic. ✨

---

🎀 SYNOPSIS 🎀

use Device::Cdio::Device;
$d = Device::Cdio::Device->new(-driver_id=>$perlcdio::DRIVER_DEVICE);
$drive_name = $d->get_device();
($i_read_cap, $i_write_cap, $i_misc_cap) =  $d->get_drive_cap();

$start_lsn = $d->get_first_track()->get_lsn();
$end_lsn=$d->get_disc_last_lsn();
$drc = $d->audio_play_lsn($start_lsn, $end_lsn);
($vendor, $model, $release, $drc) = $d->get_hwinfo();

like look at her go 😭 so much capability in so few lines.

---

💖 METHODS 💖

🦋 new

new(source, driver_id, access_mode)->$device_object

Makes you a shiny brand-new Device object. every single one of source, driver_id and access_mode can be undef — no pressure. and ngl? it's probably best to not give an access_mode at all unless you genuinely know what you're doing. i said what i said. 🙈

🎵 audio_pause

audio_pause()-> $status

Pauses the CD that's playing through the analog output. the device status gets handed back to you. 💜

🎵 audio_play_lsn

audio_play_lsn(start_lsn, end_lsn)-> $status

Plays the CD through the analog output starting at the given lsn and going all the way to the ending lsn. device status comes back. simple as. ✨

🎵 audio_resume

audio_resume()-> $status

Un-pauses — resumes playing the audio CD through the analog interface. device status is returned. 🫶

🎵 audio_stop

audio_stop()-> $status

Stops the audio CD playing through the analog interface. device status returned, as always. 🎀

💅 close

close()->bool

Frees up the resources tied to cdio. call this when you're done using the CD reading/control operations for the current device — like, actually done done, not "done but let me do one more thing" done. ✨

💅 eject_media

eject_media()->drc

Ejects the media in the CD drive if there's a routine around that can do it. status gets returned. 💖

🦋 get_arg

get_arg(key)->string

🦋 get_device

get_device()->str

Gets the default CD device.

If the CD object already has an opened CD, you get back the name of the device that was used. (fun fact: that's literally the same thing as calling d->get_arg("source").) 💫

And if we haven't initialized a specific device driver yet, she'll go find a suitable one and return the default device for that.

⚠️ heads up bestie: in some situations with certain drivers or OS's, we just can't find a CD device if there's no media in it — so this routine can totally return undef even though there is a hardware CD-ROM sitting right there. it's giving "not my fault". 😭

🌈 get_disc_last_lsn

get_disc_last_lsn(self)->int

Grabs the LSN of the end of the CD. $perlcdio::INVALID_LSN is what you get back if something went wrong. 💀

🌈 get_disc_mode

get_disc_mode() -> str

Gets the disc mode — as in, the kind of CD we've got goin' on: CD-DA, CD-ROM mode 1, CD-MIXED, etc. and yes, the notion of "CD" is extended a little here to include DVDs too. we're inclusive in this house. 👑

🔥 get_drive_cap

get_drive_cap()->(read_cap, write_cap, misc_cap)

Gets the drive capabilities of the device.

⚠️ and again with the caveat: in some situations of drivers or OS's we can't find a CD device if there's no media in it — and in that situation the capabilities show up as empty even though there's a hardware CD-ROM. rude? yes. true? also yes. 😭

🔥 get_drive_cap_dev

get_drive_cap_dev(device=undef)->(read_cap, write_cap, misc_cap)

Gets the drive capabilities of the device.

same warning, same energy: sometimes with certain drivers or OS's we can't find a CD device when there's no media in it, and then the capabilities come back empty even though a hardware CD-ROM exists. ✨

🌸 get_driver_name

get_driver_name()-> string

Returns a string with the name of the driver currently in use. "undef" comes back if there's an error. 🫶

🌸 get_driver_id

get_driver_id()-> int

Returns the driver id of the driver in use. and if the object hasn't been initialized, or is None, you get $perlcdio::DRIVER_UNKNOWN. 💜

🦋 get_first_track

get_first_track()->Track

Returns a Track object for the first track. if something went sideways you'll get $perlcdio::INVALID_TRACK or $perlcdio::BAD_PARAMETER back. no cap. 🌈

🎀 get_hwinfo

get_hwinfo()->(vendor, model, release, drc)

Gets the CD-ROM hardware info by way of a SCSI MMC INQUIRY command. an exception is raised if we hit an error — so like, be aware. 💀

🔊 audio_get_volume

my($arr, $rc) = $dev->audio_get_volume;

Returns the volume settings of the device's 4 channels plus the device return code. in a scalar context you only get the device return code! check perlcdio::driver_errmsg($rc) to find out what the return values actually mean when "$rc != 0". 🎧

🔊 audio_play_track_index

$drc = $dev->audio_play_track_index($start_track, $start_index, $end_track, $end_track);

Plays the CD through the analog output starting at the track and index you want, running until the end track and index. tracks have to be inside the valid CD track range 0..99, so no funny business. ✨

just like a track number gets burned into the CD, so does an index for a track. 🔥

see perlcdio::driver_errmsg($drc) to decode the return values when "$drc != 0". 💜

🔊 audio_set_volume

$drc = $dev->audio_set_volume($channel1_volume, $channel2_volume,
                              $channel3_volume, $channel4_volume);

Sets the volume levels for channels 1–4. values from 0–255 are fair game. stereo CDROM devices (which, let's be real, is most of them) only use channels 1 and 2. 🎚️

use -1 when you want the existing value kept — it's the "no thoughts, keep as is" option. see perlcdio::driver_errmsg($drc) for what the return values mean when "$drc != 0". 🎀

📝 get_disk_cdtext, get_track_cdtext

$hash = $dev->get_disk_cdtext;
$hash = $dev->get_cdtext_for_track(track, field);
$hash = $dev->get_cdtext_field_for_track(track, field);
$hash = $dev->get_cdtext_field_for_track(track, field);

Returns a hash reference hash->{cdtext_field}="text" if it found any cdtext on the disk. 🦋

📝 get_disk_cdtext_field_for_track

$str = $dev->get_cdtext_field_for_track($field, $track=0, $cdtext=$self->{cdtext});

Returns the text associated with field $field of track $track of $cdtext, if there is any. 💜

🧹 cdtext_destroy

$dev->cdtext_destroy()

Removes the CD-TEXT memory resources associated with a disc and sets $dev->{cdtext} to undef. 🧼

Use this when you're done accessing CD-TEXT information — clean up after yourself, bestie.

Note: $def->close() runs this as part of its operation. so it's handled for you there. ✨

🔢 get_cddb_discid

$discid = $dev->get_cddb_discid;

Returns the calculated cddb discid integer. usually it's used as a hexstring! 🎀

🎧 audio_get_status

my($hash, $drc) = $dev->audio_get_status;

Returns a hash reference packed with the audio-subchannel-mmc status values: 🌈

• audio_status — value
• status_text — audio_status as text (INVALID,ERROR,NO_STATUS,UNKNOWN,playing,paused,completed)
• track — track number
• index — index in track
• msf time values as ints minutes, seconds, frames:
  • abs_m,abs_s,abs_f — total disc time played
  • rel_m,rel_s,el_f — track time played
• disk_s — seconds disk played
• track_s — seconds track played
• address
• control

🚪 is_tray_open

$dev->is_tray_open

Returns true if the tray seems open, 0 otherwise. she's just guessing, but she's confident. 💅

🦋 get_joliet_level

get_joliet_level()->int

Returns the Joliet level recognized for cdio. this only makes sense for something that actually has an ISO-9660 filesystem, so don't come at her otherwise. ✨

🦋 get_last_session

get_last_session(self) -> (track_lsn, drc)

Gets the LSN of the first track of the last session on the CD. 🎀

🦋 get_last_track

get_last_track()->Track

Returns a Track object for the last track. $perlcdio::INVALID_TRACK or $perlcdio::BAD_PARAMETER comes back if there was a problem. 💜

🦋 get_mcn

get_mcn()->str

Gets the media catalog number (MCN) off the CD. 🔥

🦋 get_media_changed

get_media_changed() -> int

Finds out whether the media has changed since the last call. returns 1 if it has changed since the last call, 0 if it hasn't. a negative number means the driver status error. so watch the sign, bestie. 👀

🔮 guess_cd_type

$hash = $dev->guess_cd_type($lsn,$track);

Tries to figure out what kind of CD-image and/or filesystem we've got at track $track. the first argument is the start lsn of track $track. returns a hash reference with these keys: 💫

• cdio_fs_t — (enum cdio_fs_t from libcdio) FIXME: add text
• cdio_fs_cap_t — (enum cdio_fs_cap_t from libcdio) FIXME: add text
• joliet_level — if it has Joliet extensions, this is the associated level number (i.e. 1, 2, or 3).
• iso_label — 32 byte ISO fs label.
• isofs_size — size of ISO fs.
• UDFVerMajor — UDF fs version.
• UDFVerMinor — UDF fs version.

🔢 get_num_tracks

get_num_tracks()->int

Returns the number of tracks on the CD. $perlcdio::INVALID_TRACK gets raised on error. 😤

🦋 get_track

get_track(track_num)->track

Sets a new track object of the current disc for the track number you handed over. 🎀

🦋 get_track_for_lsn

get_track_for_lsn(LSN)->Track

Finds the track that contains LSN. undef comes back if the lsn is outside the CD, or if something errored out. 💀

If the LSN is before the pregap of the first track, you get a track object with a 0 track. otherwise she returns the track that spans the lsn. that's the rule. ✨

🦋 have_ATAPI

have_ATAPI()->bool

Returns 1 if the CD-ROM understands ATAPI commands. 💅

📍 lseek

lseek(offset, whence)->int

Repositions the read offset. similar to (if not the same as) libc's fseek(). 🎯

offset is how much to seek, and whence is like the corresponding parameter in libc's lseek, e.g. it should be SEEK_SET or SEEK_END.

the offset is returned — or -1 on error. 💜

📂 open

open(source=undef, driver_id=$libcdio::DRIVER_UNKNOWN,
     access_mode=undef)->$cdio_obj

Sets you up to read from the place specified by source, driver_id and the access mode. this should be called before using any other routine except the ones that act on a CD-ROM drive by name. it also gets implicitly called whenever a new is done specifying a source or driver id. so she's a lil automatic like that. ✨

If undef is given as the source, we'll use the default driver device. if undef is given as the driver_id, we'll go find a suitable device driver. the device gets opened so all your subsequent operations can actually happen. 🔥

📖 read

read(size)->(size, data)

Reads the next size bytes. similar to (if not the same as) libc's read(). 🦋

The number of bytes read and the data both come back to you. 💜

📖 read_data_blocks

read_data_blocks(lsn, blocks=1)->($data, $size, $drc)

Reads a number of data sectors (AKA blocks). 📦

lsn is the sector to read, blocks is the number of bytes.

The size of the data will be a multiple of $perlcdio::ISO_BLOCKSIZE. 🌈

The number of data, the size of the data, and the return code status all come back in an array context. in a scalar context you just get the data. and "undef" is returned as the data on error. 💀

📖 read_sectors

read_sectors($lsn, $read_mode, $blocks=1)->($data, $size, $drc)
read_sectors($lsn, $read_mode, $blocks=1)->$data

Reads a number of sectors (AKA blocks). 🎀

lsn is the sector to read, bytes is the number of bytes.

If read_mode is $perlcdio::MODE_AUDIO, the return data size will be a multiple of $perlcdio::CDIO_FRAMESIZE_RAW i_blocks bytes. 🎵

If read_mode is $perlcdio::MODE_DATA, the data will be a multiple of $perlcdio::ISO_BLOCKSIZE, $perlcdio::M1RAW_SECTOR_SIZE or $perlcdio::M2F2_SECTOR_SIZE bytes — depending on what mode the data is in. ✨

So like, if read_mode is $perlcdio::MODE_M2F1, bestie, your data comes back as a multiple of $perlcdio::M2RAW_SECTOR_SIZE bytes. No cap. 🌸

And if read_mode is $perlcdio::MODE_M2F2? Then the return data size is gonna be a multiple of $perlcdio::CD_FRAMESIZE bytes. Slay. ✨

Now the way context changes everything: in an array context you get back the number of data, the size of the data, and the return code status — the whole trio, iconic. In a scalar context you just get the data, periodt. And on error? undef is returned as the data. 😭 yes it will simply hand you undef, be normal about it.

---

🎀 set_blocksize 🎀

set_blocksize(blocksize) -> $status

Sets the blocksize for all the reads that come after this. And yeah, the operation status code gets returned to you. 💅

🌈 set_speed 🌈

set_speed(speed)->drc

That's it, that's the whole vibe — the operation status code is returned. Go off. ⭐

🧚 read_pvd 🧚

$pvd = $dev->read_pvd;

This one reads the ISO-9660 Primary Volume Descriptor (PVD) off the disk and hands it right back to you. Then you can use stuff like perliso9660::get_pvd_type($pvd) … and the other methods to pull the values out of it. Obsessed. 🦋

---

✨ SEE ALSO ✨

• Device::Cdio — for the top-level module, it's giving main character 😌
• Device::Cdio::Track — for track objects
• Device::Cdio::ISO9660 — for when you're working with ISO9660 filesystems
• perlcdio — the lower-level interface to libcdio, iykyk
• <http://www.gnu.org/software/libcdio> — this has the documentation on libcdio, including a manual and the API via doxygen. Go read it, fr fr. 📚

💖 AUTHORS 💖

Rocky Bernstein — that's the author, bestie, respect. 👑

👑 COPYRIGHT 👑

Copyright (C) 2006, 2008, 2017 Rocky Bernstein <rocky@cpan.org>

Okay so legally speaking, this program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation — either version 3 of the License, or (at your option) any later version. Pick your fighter. 💅

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY — no, literally, not even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. That's a big deal, don't skip it. See the GNU General Public License for more details. 🫶

You should have received a copy of the GNU General Public License along with this program. If not, see The GNU General Public License at <http://www.gnu.org/licenses/#GPL>.

---

🌟 and that's the page, babe. perl v5.42.3, dated 2026-08-19, from the Device...Device(3pm) era of the perl docs — go forth and read those sectors, you absolute icon. 💜🌈