H2CLI(1)

NAME
h2cli - a CLI version of the advanced drum machine Hydrogen.

SYNOPSIS

h2cli options

DESCRIPTION

h2cli does not start up the GUI of Hydrogen but allows to do some batch processing using its core. It can be used in two different ways. Either for exporting a song into an audio file or for checking, extracting, installing, or upgrading an existing drumkit.

OPTIONS

-d, --driver=[AUDIO_DRIVER]
    Use the selected audio driver. The description of this option in the --help output contains all audio drivers available on your system.

-s, --song=FILE
    Load a song (*.h2song) at startup. Alternatively, you can just pass the filename without this option.

-p, --playlist=FILE
    Load a playlist (*.h2playlist) at startup.

-k, --kit=DRUMKIT_NAME
    Load a drumkit at startup.

-o, --outfile=PATH
    Destination file (export).

-r, --rate=INT
    Set bitrate while exporting a song.

-b, --bits=INT
    Set bit depth while exporting a song.

--compression-level=DOUBLE
    Trade-off between max. quality (0.0) and max. compression (1.0) while exporting a song.

-I, --interpolation=INT
    Type of interpolation used during resampling (if required) while exporting a song. Available options are 0 (linear) [default], 1 (cosine), 2 (third), 3 (cubic), and 4 (hermite).

-i, --install=FILE
    Install a drumkit (*.h2drumkit).

-c, --check=FILE
    Validates a drumkit (*.h2drumkit) against the current drumkit format.

-l, --legacy-check=FILE
    Validates a drumkit (*.h2drumkit) against the current as well as legacy drumkit formats.

-u, --upgrade=FILE
    Upgrades a drumkit. The provided file can be either an absolute path to a folder containing a drumkit, an absolute path to a drumkit file (drumkit.xml) itself, or an absolute path to a compressed drumkit (*.h2drumkit). If no target folder was specified using the -t option, a backup of the drumkit is created and the original one is upgraded in place. If a compressed drumkit is provided as first argument, the upgraded drumkit will be compressed as well.

-x, --extract=FILE
    Extracts the content of a drumkit (*.h2drumkit). If no target is specified using the -t option, this command behaves like --install.

-t, --target=FOLDER
    Target folder the extracted (-x) or upgraded (-u) drumkit will be stored in. The folder is created if it does not exists yet.

-O, --osc-port=PORT
    Use custom OSC port.

-P, --data=PATH
    Use an alternate system data path.

--user-data=PATH
    Use an alternate user data path.

    The default one is $HOME/.hydrogen.

--config=PATH
    Use an alternate config path.

    The default one is $HOME/.hydrogen/hydrogen.conf.

-V, --verbose=[LEVEL]
    Print a lot of debugging info

    Level, if present, may be None, Error, Warning, Info, or Debug.

-L, --log-file=FILE
    Use custom log file.

-T, --log-timestamps
    Add timestamps to all log messages.

-v, --version
    Show version info.

-h, --help
    Show this help message.

FILES
For a comprehensive list of files, configuration, and environmental variables, please see the man page of hydrogen itself.

EXAMPLES
Exporting a song into an audio file

    h2cli -s /usr/share/hydrogen/data/demo_songs/GM_kit_demo1.h2song -d GMRockKit -d auto -o ./example.wav

Check the format of a drumkit

    h2cli -c /usr/share/hydrogen/data/drumkits/GMRockKit

BUGS & FEATURES REQUEST

If you find any bug or if you would like to propose a new feature, please report it to https://github.com/hydrogen-music/hydrogen/issues

AUTHORS

The hydrogen development team. See complete list at Hydrogen's "About" Dialog. You can contact them at <hydrogen-devel@lists.sourceforge.net>.

Subscription to the mailing list can be done here :
    http://lists.sourceforge.net/lists/listinfo/hydrogen-devel .

SEE ALSO
The main graphical application
    hydrogen(1)

A player Hydrogen-based songs on the command line
    h2player(1)

COPYRIGHT AND LICENSE
Copyright (C) 2002-2008 Alessandro Cominu
Copyright (C) 2008-2025 The hydrogen development team

Hydrogen is free software; you can redistribute it and/or modify it under the terms of the GPL version 2 or later.