=head1 NAME

Audio::Cuefile::Libcue

=head1 VERSION

Version 2.3.0

=head1 SYNOPSIS

Perl interface to the C<libcue> cuesheet reading library

=head1 USAGE

  use Audio::Cuefile::Libcue;

  my $cuesheet = cue_from_string($string);
  print Dumper($cuesheet);

=head1 DESCRIPTION

This is a Perl interface to C<libcue>, a cuesheet parsing library written in C.
C<libcue> itself was forked from the C<cuetools> project and further enhanced.
The library can read cuesheets in many common formats.

The C interface is made available to Perl, but users should not need those.
Instead, use the one-shot parsing functions to read a cuesheet into a Perl data
structure.

=head2 Perl Interface

  my $cue = cue_from_string($string);

  # or if you have an open filehandle,
  $cue = cue_from_file($filehandle);

These two functions read a cuefile from a string or open filehandle, parse it
using the C functions, and return a hash structure.  The filehandle can be closed
after this call.

An example of the Perl usage is in F<t/perl_interface.t>.  Note that the C<tracks> and C<index>, despite being numeric, are stored as string hash keys.  Use a numeric sort (C<sort { $a E<lt>=E<gt> $b }>) when iterating through the keys.

=head2 C Interface

If preferred, the C functions from F<libcue.h> are mapped into Perl functions, with the exception of C<cd_delete()> as it is automatically called when needed.  

  # Open a cuesheet
  my $cd = cue_parse_string($cue);

  print "Tracks in CD: " . cd_get_ntrack($cd) . "\n";

  $track_1 = cd_get_track( $cd, 1 );
  print "Track 1 filename: " . track_get_filename($track_1) . "\n";
  # etc

Refer to C<libcue> for a list of available functions, or F<t/c_interface.t> for further examples.

=head2 Exportable functions

  # Perl interface
  cue_from_string($string)
  cue_from_file($filehandle)

  // C interface
  struct Cd* cue_parse_file(FILE* fp)
  struct Cd* cue_parse_string(const char* string)

  enum DiscMode cd_get_mode(const struct Cd *cd)
  const char *cd_get_cdtextfile(const struct Cd *cd)

  struct Cdtext *cd_get_cdtext(const struct Cd *cd)
  struct Cdtext *track_get_cdtext(const struct Track *track)
  const char *cdtext_get(enum Pti pti, const struct Cdtext *cdtext)

  struct Rem* cd_get_rem(const struct Cd* cd)
  struct Rem* track_get_rem(const struct Track* track)
  const char* rem_get(enum RemType cmt, const struct Rem* rem)

  int cd_get_ntrack(const struct Cd *cd)
  struct Track *cd_get_track(const struct Cd *cd, int i)

  const char *track_get_filename(const struct Track *track)
  long track_get_start(const struct Track *track)
  long track_get_length(const struct Track *track)
  enum TrackMode track_get_mode(const struct Track *track)
  enum TrackSubMode track_get_sub_mode(const struct Track *track)
  int track_is_set_flag(const struct Track *track, enum TrackFlag flag)
  long track_get_zero_pre(const struct Track *track)
  long track_get_zero_post(const struct Track *track)
  const char *track_get_isrc(const struct Track *track)
  long track_get_index(const struct Track *track, int i)

None of the constants are exportable.

=head1 HISTORY

=over

=item 2.3.0

Original version; created by h2xs 1.23 with options

        -A
        -C
        -b
        5.6.2
        -v
        2.3.0
        -n
        Audio::Cuefile::Libcue
        -x
        libcue/libcue.h

=back

=head1 SEE ALSO

L<https://github.com/greg-kennedy/p5-Audio-Cuesheet-Libcue> - repository for Audio::Cuesheet::Libcue development

L<https://github.com/lipnitsk/libcue> - repository for the C libcue library

Other Cuesheet modules:

=over

=item * L<Audio::Cuefile::Parser>, an older pure Perl cuesheet parser

=item * L<Audio::Cuefile::ParserPlus>, a newer Perl module which can also I<write> cuesheets.

=item * L<MP3::Tag::Cue>, a cue parser that makes part of L<MP3::Tag>.

=back

=head1 REFERENCES

L<https://en.wikipedia.org/wiki/Cue_sheet_(computing)> - Wikipedia article on Cuesheets

L<https://wiki.hydrogenaud.io/index.php?title=Cue_sheet> - Hydrogen Audio article on Cuesheets, with more detail and examples

=head1 AUTHOR

Greg Kennedy, E<lt>kennedy.greg@gmail.comE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2024 by Greg Kennedy

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.36.3 or,
at your option, any later version of Perl 5 you may have available.