=======
 Dnuos
=======

.. contents::

About
=====

Dnuos is a console program that creates lists of music collections, based on
directory structure.

For example, a list might look like this::

    Album/Artist                       |  Size | Type | Quality
    ===========================================================
    Ambient                            |       |      | 
        Alva Noto                      |       |      | 
            2001 - Transform           | 70.9M | MP3  | -V2
            2004 - Transrapid          | 30.2M | MP3  | -aps
            2005 - Transspray          | 31.7M | MP3  | -aps
            2005 - Transvision         | 32.3M | MP3  | -aps
        Alva Noto and Ryuichi Sakamoto |       |      | 
            2002 - Vrioon              | 72.6M | MP3  | -aps
            2005 - Insen               | 99.1M | MP3  | 320 C
            2006 - Revep               | 27.9M | MP3  | -V2n

The list format is completely customizable and can be plain text or HTML.

Dnuos supports MP3, AAC, Musepack, Ogg Vorbis, and FLAC audio files. Quality
profile detection is also supported, including `LAME quality preset`_
information.

Audio file information is saved to disk after a list is made for the first
time, making subsequent lists much faster to generate. Only audio files and
directories that have been changed since the last list was made are
analyzed.

Dnuos is based on code from Oidua_. Oidua makes similar lists, but is much
older, has fewer features, and is no longer maintained.

.. _LAME quality preset: http://wiki.hydrogenaudio.org/index.php?title=Lame#Recommended_encoder_settings
.. _Oidua: http://oidua.suxbad.com/


Download
========

Releases can be found in http://dnuos.tweek.us/files/.


Installation/Usage
==================

Run ``dnuos --help`` for a full rundown of the available options.


Linux, Mac OS X, Unix
---------------------

If you wish to install Dnuos with setuptools_ (which comes bundled with Mac OS
X, for instance), download and run `ez_setup.py`_, and simply run the following
command::

    sudo easy_install dnuos

Otherwise, run ``setup.py`` with the version of Python you wish to install
Dnuos with::

    sudo python2.5 setup.py install

This will install Dnuos into your ``site-packages`` folder, and will add a
console script named ``dnuos`` (usually in ``/usr/bin/`` or
``/usr/local/bin/``).

Once installed, open up your favorite terminal emulator and run ``dnuos``. On
Mac OS X, *Terminal* might be a good choice (located in
``/Applications/Utilities/``).


.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
.. _`ez_setup.py`: http://peak.telecommunity.com/dist/ez_setup.py


Windows
-------

There's no installation. Just extract the zip file where you want to install
it. You can run the program in the command prompt with ``dnuos.exe``.

After extracting Dnuos, press the Windows key and R to bring up the *Run*
dialog. Type *cmd* and press enter to start the command prompt. Then type the
drive letter the ``.exe`` is on, and ``cd`` to the directory with the ``.exe``
file. From here, simply run ``dnuos.exe``.


Graphical Front-ends
--------------------

If terminals and command prompts aren't to your liking, you can try one of
the following graphical front-ends instead:

Guidua_
    A graphical front-end for Windows.
QtOIDUA_
    A graphical front-end for Linux and Mac OS X. (Note: Versions 0.08 and
    older have a bug which prevents QtOIDUA from working with Dnuos 1.0)
    

.. _Guidua: http://oidua.suxbad.com/setup_guidua_0.16.exe
.. _QtOIDUA: http://www.spoonfedmonkey.com/software/qtoidua/


News
====

Version 1.0b5 (Feb. 23, 2008)
    Added ``-L``/``--list-files`` for listing individual files in
    directories. Information about individual files isn't cached, however.

    Added ``-u``/``--unknown-types`` for listing directories with unsupported
    audio types.

    Fixed creation of the cache directory failing.

Version 1.0b4 (Feb. 22, 2008)
    Added support for locale-specific number formatting.

    Fixed Audiolist tag crashing on VBR MP3s.

    Fixed crashing on inaccessible directories (now ignored).

    Added support for gettext-based translation.

    Added a French translation.

    Fixed theoretically possible zero division error with ``-t``/``--time``.

    Fixed issues with the cache not caching correctly (and non-existent
    directories now get culled from the cache).

    Improved the cache implementation so it's loaded incrementally instead
    of all at once before a list is printed.

    Fixed ``-e`` exclude directory switch not working with relative paths.

    Fixed crash with ``-w``/``--wildcards``.

    Fixed ``-m``/``--merge`` not working properly on Windows.

    Improved unit test coverage and fixed Windows portability issues.

Version 1.0b3 (Dec. 25, 2007)
    Added support for saving the cache even when Dnuos is interrupted.

    Renamed ``-p``/``--parallel`` back to ``-m``/``--merge``, as it does
    just that.

    Fixed ``-i``/``--ignore-case`` not working.

    Marginal speed improvements in ``audiotype`` and ``id3`` code.

    Removed a substantial amount of unused code in the ``id3`` package.

    Fixed possible crash with new vendor output field in certain cases.

    Fixed parsing errors with Ogg Vorbis files and added vendor support.

    Reduced win32 package size.

Version 1.0b2 (Dec. 7, 2007)
    Updated and consolidated documentation.

    Fixed ``setup.py sdist`` not including all files.

    Fixed handling of MP3s with VBRI headers (e.g. made by Fraunhofer).

    Fixed serious issues with ID3 code that made it probably never work.

    Fixed an import of ``set()`` (should improve Python 2.3 compatibility).

    Switched from ``pickle`` to ``cPickle`` (when available) and switched to
    the most efficient pickle format (should speed things up quite a bit).

    Made cache directory finding more robust.

    Added support for saving the cache mid-list, so if you cancel making a
    list, it'll cache what it already listed.

    Added a friendly error message for output strings with invalid fields.

    Added a Makefile that runs ``setup.py``.

Version 1.0b1 (Dec. 2, 2007)
    Significant code overhaul.

    Added audio metadata caching.

    Added the ability to filter out directories with mixed files.

    Added proper ``distutils``/``setuptools`` support.

    Added AAC bitrate calculation support.

    Added ``V`` output flag that prints the encoder info (only MP3s for now).

    Cleaned up help message (uses ``optparse`` now).

    Removed ``-m``/``--merge`` switch.

    Dropped support for Python 2.2.

Version 0.94 (Jan. 16, 2006)
    Fixed endianness issues on big-endian machines.

Version 0.93 (Jan. 13, 2006)
    Fixed regression with MP3 header detection.

    Added experimental VBRI header support.

Version 0.92 (Jan. 13, 2006)
    The ``-l`` (LAME MP3s only) and ``-v`` (VBR MP3s only) switches now work
    in regular output.

    Added ``-b`` switch. Allows filtering of MP3s with bit rates lower than
    specified by ``-b``.

Version 0.91 (Jan. 12, 2006)
    Made finding of MP3 headers more robust. MP3s encoded at ``-V 9`` with
    LAME 3.97b1 no longer confuse Dnuos.

Version 0.9 (Jan. 11, 2006)
    Finally forked Oidua! This is now DNUOS!


Development
===========

The official development repository can be found at
http://dnuos.tweek.us/hg/. Download using Mercurial_::

    hg clone http://dnuos.tweek.us/hg/ my-dnuos

Running the test suite requires nose_, and the `test data`_. Once you have
both, you can run the tests with the following command::

    ./setup.py test

If you find any problems, please submit a ticket on the `Trac site`_. The
Trac site is for development, not support, so please don't submit help
requests there.

.. _Mercurial: http://www.selenic.com/mercurial/
.. _nose: http://somethingaboutorange.com/mrl/projects/nose/
.. _test data: http://dnuos.tweek.us/files/testdata.zip
.. _Trac site: http://dnuos.tweek.us/trac/


Contact
=======

`Mattias Päivärinta <pejve at vasteras2 dot net>`_
    Senior programmer.
`Brodie Rao <me+dnuos at dackz dot net>`_
    Project maintainer.
