abc filter

← Back to Filter List


↓ examples

Runs `abcm2ps` on .abc music files.

Aliases for this filter

  • abc

Converts from file formats:

  • .abc

To file formats:

  • .svg
  • .html
  • .xhtml
  • .eps

Available settings:

add-new-filesBoolean or list of extensions/patterns to match.False
added-in-versionDexy version when this filter was first available.
additional-doc-filtersFilters to apply to additional documents created as side effects.{}
additional-doc-settingsSettings to apply to additional documents created as side effects.{}
argsArguments to be passed to the executable.
check-return-codeWhether to look for nonzero return code.True
clargsArguments to be passed to the executable (same as 'args').
command-stringThe full command string.%(prog)s %(args)s %(format)s -O %(output_file)s %(script_file)s
data-typeAlias of custom data class to use to store filter output.generic
envDictionary of key-value pairs to be added to environment for runs.{}
examplesTemplates which should be used as examples for this filter.['abc']
exclude-add-new-filesList of patterns to skip even if they match add-new-files.[]
exclude-new-files-from-dirList of directories to skip when adding new files.[]
executableThe executable to be runabcm2ps
extFile extension to output.None
ext-to-formatA dict of mappings from file extensions to format flags that need to be passed on the command line, e.g. for ragel with ruby host language .rb => -R{'.eps': '-E', '.html': '-X', '.svg': '-g', '.svg1': '-v', '.xhtml': '-X'}
extension-mapDictionary mapping input extensions to default output extensions.None
helpHelpstring for plugin.Runs `abcm2ps` on .abc music files.
input-extensionsList of extensions which this filter can accept as input.['.abc']
keep-originalsWhether, if additional-doc-filters are specified, the original unmodified docs should also be added.False
make-dummy-outputWhether to make a dummy output file when one is not generated and add-new-files is True.False
mkdirA directory which should be created in working dir.None
mkdirsA list of directories which should be created in working dir.[]
nodocWhether filter should be excluded from documentation.False
outputWhether to output results of this filter by default by reporters such as 'output' or 'website'.True
output-extensionsList of extensions which this filter can produce as output.['.svg', '.html', '.xhtml', '.eps']
override-workspace-exclude-filtersIf True, document will be populated to other workspaces ignoring workspace-exclude-filters.False
path-extensionsstrings to extend path with[]
preserve-prior-data-classWhether output data class should be set to match the input data class.False
record-varsWhether to add code that will automatically record values of variables.False
require-outputShould dexy raise an exception if no output is produced by this filter?True
scriptargsArguments to be passed to the executable.
tagsTags which describe the filter.['music']
use-wdWhether to use a custom working directory when running filter.True
variablesA dictionary of variable names and values to make available to this filter.{}
varsA dictionary of variable names and values to make available to this filter.{}
version-commandCommand to call to return version of installed software.None
windows-version-commandCommand to call on windows to return version of installed software.None
workspace-exclude-filtersFilters whose output should be excluded from workspace.['pyg']
workspace-includesIf set to a list of filenames or extensions, only these will be populated to working dir.None
write-stderr-to-stdoutShould stderr be piped to stdout?True

ABC Filter

ABC is a music notation which looks like this:

% Generated more or less automatically by swtoabc by Erich Rickheit KSC
T:Jingle Bells
 G/2G/2| G e d c| G3 G/2G/2| G e d c| A3 z/2 A/2| B f e d| B3 z/2 B/2|\
 g g f d| e3 G/2G/2| G e d c| G3 G/2G/2| G e d c| A3 z/2 A/2| B f e d|\
 g g g3/2 g/2| a g f d| c3 g| e e e2| e e e2| e g c3/2 d/2| e3 z| f f f3/2 f/2|\
 f e e e/2e/2| e d d e| d2 g2| e e e2| e e e2| e g c3/2 d/2| e3 z|\
 f f f3/2 f/2| f e e e/2e/2| g g f d| c3||

The abc filter converts this to one of the available output formats, using the abcm2ps utility which must be installed on your system. By default it will convert to SVG:

- jingle.abc|abc

Here is some of the SVG generated:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
<svg xmlns="http://www.w3.org/2000/svg" version="1.1"
    width="701.60px" height="458.00px">
<style type="text/css">
.fill {fill: currentColor}
.stroke {stroke: currentColor; fill: none}

To get EPS or another type of output, set the desired file extension:

- jingle.abc|abc|-:
    - abc: { 'ext' : '.eps' }

Here is some of the EPS generated:

%!PS-Adobe-2.0 EPSF-2.0
%%BoundingBox: 0 0 526 344
%%Title: jingle.abc (1)
%%Creator: abcm2ps-8.14.2
%%CreationDate: Mar 31, 2020 22:11
%%LanguageLevel: 3
%CommandLine: -E -O jingle.eps jingle.abc


You can also run the dexy eps2pdf filter to generate a PDF. In this case you don't need to specify any custom file extension because eps2pdf only accepts .eps files as inputs. In this example, we also set some custom command line arguments which get passed to abcm2ps:

- jingle.abc|abc|eps2pdf:
    - abc: { 'args' : '-s 2 -l' }

Here is the resulting PDF.

To generate HTML you can use the shortcut h filter which forces the previous filter to output HTML:

- jingle.abc|abc|h

The HTML output format wraps SVG output in a self-contained HTML page.

Filter Source Code
class AbcFilter(SubprocessFormatFlagFilter):
    Runs `abcm2ps` on .abc music files.
    aliases = ['abc']
    _settings = {
            'command-string' : '%(prog)s %(args)s %(format)s -O %(output_file)s %(script_file)s',
            'add-new-files' : False,
            'output' : True,
            'tags' : ['music'],
            'examples' : ['abc'],
            'executable' : 'abcm2ps',
            'input-extensions' : ['.abc'],
            'output-extensions': ['.svg', '.html', '.xhtml', '.eps'],
            'ext-to-format': {
                '.eps' : '-E',
                '.svg' : '-g',
                '.svg1' : '-v', # dummy entry so we know -v is a format flag
                '.html' : '-X',
                '.xhtml' : '-X'

    def process(self):
        command = self.command_string()
        proc, stdout = self.run_command(command, self.setup_env())
        self.handle_subprocess_proc_return(command, proc.returncode, stdout)

        if self.ext in ('.svg', '.eps'):
            # Fix for abcm2ps adding 001 to file name.
            nameparts = os.path.splitext(self.output_data.name)
            output_filename = "%s001%s" % (nameparts[0], nameparts[1])
            output_filepath = os.path.join(self.workspace(), output_filename)

        if self.setting('add-new-files'):

Content © 2020 Dr. Ana Nelson | Site Design © Copyright 2011 Andre Gagnon | All Rights Reserved.