####
Burn
####

..  rubric:: “Burn until recorded, now!”

..  contents::
    :depth: 2

About
=====

Burn is a simple program/script written in Python.

It's aim is to make it simple and quick to burn CDs or DVDs.

First of all Burn...

* ... has to be a command line program/script;

* ... must perform any of its feature invoking it only once and with
  one and only one command line.

Burn should be able to:

* create Audio CD from .ogg, .mp3, .wav (even toghether)
* copy CDs
* create Data-CD or DVD (storage, backups, etc.)
* create a CD or DVD from an existing ISO image.

Burn still performs above features. Other things burn does:

* size of stuff to be burned.

* compute if there is enough free space for temporary files (images
  and audio files).

* warns if size is bigger than CD/DVD capacity

* convert .mp3 and .ogg in .wav without external decoders

* perform burn simulations for testing

* eject CD/DVD at the end of burn process

* asks if you want to see what is going to be burned (mounts and
  umount image)

* asks if you want to make other copies

* shows main id3 tags for .mp3 and .ogg files

Requirements
============

In order to work, burn requires:

* `python`_ (version 2.4 or later)

* `cdrkit`_ (wodim, genisoimage, cdrdao)

* `eyeD3`_

* `pyogg`_ (python-pyvorbis) (generic Ogg Vorbis modules for Python).

..  _python: http://www.python.org/
..  _cdrkit: http://cdrkit.org/
..  _eyeD3: http://eyed3.nicfit.net/releases/
..  _pyogg: http://ekyo.nerim.net/software/pyogg/

**Optionally**: you can choose not to decode mp3 and ogg files with
native burn functions choosing to do it with external decoders. If you
wanto to do so, you have to install preferred decoders (ogg123,
mpg321, mpg123, etc.) and set up burn.conf. (remember: lame uses
mpg123 to convert to wav).

..  admonition:: Warning PowerPC users

    Internal decoder (mp3 to wav) does not work. Please use external
    decoding.

Quick start
===========

First of all, remember following points:

1.  first argument has to be one of the burn modes:

    * ``-A`` for Audio-CD
    * ``-D`` for Data-CD/DVD
    * ``-I`` for ISO-CD/DVD
    * ``-C`` for Copy-CD/DVD

2.  you can test burn commands using ``-s`` option after MODE, in this
    way you can always perform a CD/DVD writing simulation. So you
    don't have to waste CDs/DVDs to test it.

Examples
--------

Here are some commands that help you start using burn quickly.

Creates a CD/DVD with /etc/ contents::

    # burn -D -p /etc/

(you will find files and directories contained in /etc in CD's root.)

Creates a CD/DVD with spain.tar.gz in CDs root::

    # burn -D -p /home/bigpaul/video/summer_2003/spain.tar.gz

Creates a CD/DVD containing the whole /etc/ directory::

    # burn -D -r /etc/

(-r preserves path)

Creates a CD/DVD containing the whole /home/bigpaul/Mail renamed into
/mail_2003::

    # burn -D -c /mail_2003 /home/bigpaul/Mail -p /boot/vmli*

(-c changes path name). This command also adds in CD's root every
vmli* file in /boot/ directory

Burns image.iso::

    # burn -I -n image.iso

Copy CDs/DVDs::

    # burn -C

Creates an Audio CD. Tracks come from wav files::

    # burn -A -a *.wav

Creates an Audio CD. Tracks come from mp3 files::

    # burn -A -a *.mp3

Creates an Audio CD. Tracks come from Ogg Vorbis files::

    # burn -A -a *.ogg

Creates an Audio CD. Tracks come from .wav, .ogg, .mp3 files::

    # burn -A -a *.mp3 file.ogg track01.wav

Status
======

Burn already works. But it is in the early developement stage.

It already features:

* Data-CD/DVD

* Audio-CD

* Copy-CD/DVD

* ISO-CD/DVD

* image mount and view for Data-CD/DVD and ISO-CD/DVD.

* disk usage and prompt if you are going to overburn.

ToDo
====

..  include:: TODO

Download
========

Latest `stable version`_ (0.4.4)

..  _stable version: http://www.bigpaul.org/burn/download/burn-0.4.4.tar.gz

`Debian package`_

..  _Debian package: http://packages.debian.org/sid/burn/

Old CVS repository `hacknight CVS`_

..  _hacknight CVS: http://cvs.hacknight.org/cgi/viewcvs.cgi/burn/

My bzr branch at launchpad: ``bzr branch
lp:~gaetano-paolone/+junk/burn/``

Ben Finney bzr branch: ``bzr checkout
http://vcs.whitetree.org/bzr/public/burn/burn.devel/``

Main revisions are also avaible from `download directory`_

..  _download directory: http://www.bigpaul.org/burn/download/

Documentation
=============

Here is the help page. Other documents coming soon::

    usage: burn -MODE [general_option] [mode_option] ...

    For quick start you can get common examples with:

    burn -e


    options:
      -h, --help            show this help message and exit
      -e, --examples        show examples for quick startup

      Main burn MODES:
        The _have_ to be the first argument after program name
        -D, --data-cd       creates a Data CD/DVD.
        -I, --iso-cd        creates a CD/DVD from ISO.
        -C, --copy-cd       copy CD/DVD.
        -A, --audio-cd      creates an Audio CD from .wav, .mp3 and .ogg files.

      General options:
        These options could be used for every burn mode unless stated otherwise
        -s, --simulate      This option will perform a burn simulation.
        -j, --eject         This option will eject disk when burn process is over.

      Data CD Mode (-D) options:
        Data CD: adds files and directories.
        -p, --path          add file/s or path's content to CD-ROM/DVD's root.
                            e.g.: -p /cvs/myproj/ <return>. In this example we will
                            find CD-ROM/DVD's root filled with /cvs/myproj/
                            contents, but no /cvs/myproj/ will be created.
        -r, --preserve-path
                            add file/s or path's content to CD-ROM/DVD preserving
                            original path. e.g.: -r /cvs/myproj/ <return>. In this
                            example we will find /cvs/myproj/ in CD-ROM/DVD's root.
        -x, --exclude-path  every file or directory matching this string will not
                            be included.
        -cCHANGE_PATH, --change-path=CHANGE_PATH
                            usage: -c <new_path> <old_path>. With this option,
                            old_path will be named new_path in CD-ROM/DVD. e.g.: -c
                            /my_home/2004_Jan/ /home/bigpaul/ <return>. Thus
                            /home/bigpaul/ will be named  /my_home/2004_Jan/ in CD-
                            ROM/DVD.
        -l, --follow-symlink
                            this option allows burn to follow symbolic link
                            directories
        -m, --multisession  this option allows multisession CDs

      ISO CD Mode (-I) options:
        Creates a CD-ROM/DVD from an existing image.
        -nISO_NAME, --name=ISO_NAME
                            image name

      Copy CD Mode (-C) options:
        If you have both a reader and a recording unit you can perform a copy
        on-the-fly. You can also copy a CD even if you only have the recording
        unit.

      Audio CD Mode (-A) options:
        Audio CD is used to create an audio CD-ROM from .wav, .ogg and .mp3
        files. You can can use -a option to perform an Audio CD from different
        source audio files.
        -a, --audio-file    .wav, .mp3, .ogg file/s. Files must have extensions (no
                            matter if they are upper or lowercase).
        --audio-list=FILE_LIST
                            m3u playlist or file with one audio file per line.
        --clear-audiotemp   remove temporary audio files.

Authors
=======

..  include:: AUTHORS

Thanks
======

* to Flexer for this layout

* to zufus for his critical commit ;)

* to baluba for having tried to make it work in python2.1
  (unsuccesfully)

* to pivi for audio duration hint

* to farnis for his patient tests

* to giuppi for his willness of removing system calls and his
  wonderful patches.

* to ben finney for major code restyling

..
    Local variables:
    mode: rst
    coding: utf-8
    time-stamp-format: "%:y-%02m-%02d"
    time-stamp-start: "^:Date:[         ]+"
    time-stamp-end: "$"
    time-stamp-line-limit: 20
    End:
    vim: filetype=rst fileencoding=utf-8 :
