Andy Grundman
and 1 contributors


MP3::Cut::Gapless - Split an MP3 file without gaps (based on pcutmp3)


    use MP3::Cut::Gapless;
    # Cut file using a cue sheet
    my $cut = MP3::Cut::Gapless->new(
        cue => 'file.cue'
    for my $track ( $cut->tracks ) {
        $cut->write( $track );
    # Or, cut at defined points and stream the rewritten file
    my $cut = MP3::Cut::Gapless->new(
        file      => 'long.mp3',
        cache_dir => '/var/cache/mp3cut',
        start_ms  => 15000,
        end_ms    => 30000,
    open my $out, '>', '15-30.mp3';
    while ( $cut->read( my $buf, 4096 ) ) {
        syswrite $out, $buf;
    close $out;


This module performs sample-granular splitting of an MP3 file. Most MP3 splitters only split on frame boundaries which can leave gaps or noise between files due to MP3's bit reservoir. This module, which is based on the Java pcutmp3 tool, rewrites the LAME tag and adjusts the audio frames as necessary to make the split completely gapless when played with a compatible decoder that supports LAME encoder delay and padding.

There are two main ways to use this module.

1. Using a cue sheet, you can split a large input file into a series of tracks.

2. Realtime transcoding can be performed by specifying an input file and a start/end time, after which the rewritten MP3 can be streamed to an audio device.


new( %args )


        cue => $cue_sheet

    Optional. Cue sheet to use to determine cut points.

        file => $file_to_cut

    If not specified, the FILE entry from the cue will be used.

        start_ms => $start_time_in_milliseconds
        end_ms   => $end_time_in_milliseconds

    Optional, can be used to manually define cut points.

        cache_dir => "/path/to/cache/dir"

    Optional. When new() is called, a complete scan must be done of the MP3 file to determine the number of frames and their locations. This can be somewhat time-consuming depending on the size of the file, disk/network speed, and so on. A cache file can be created to avoid this operation if the file needs to be cut a second time. This is most useful when manually cutting a file several times.


Returns an array of MP3::Cut::Gapless::Track objects. Only available if a cue sheet was used.

write( $track, [ $filename ] )

Write the given MP3::Cut::Gapless::Track object to a file. If no filename is provided, the default filename is "<position> - <performer> - <title>.mp3". If the file already exists, it will not be overwritten.

read( $buf, $block_size_hint )

Reads a chunk of the rewritten MP3 file into $buf. Returns the number of bytes read. Only complete MP3 frames are returned, so you may receive more or less data than $block_size_hint.


pcutmp3 originally by Sebastian Gesemann



Andy Grundman, <>


Copyright (C) 2010 Logitech, Inc.

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 2 of the License, or (at your option) any later version.