What is it?


Mscgen is a small program that parses Message Sequence Chart descriptions and produces PNG, SVG, EPS or server side image maps (ismaps) as the output. Message Sequence Charts (MSCs) are a way of representing entities and interactions over some time period and are often used in combination with SDL. MSCs are popular in Telecoms to specify how protocols operate although MSCs need not be complicated to create or use. Mscgen aims to provide a simple text language that is clear to create, edit and understand, which can also be transformed into common image formats for display or printing.

This program and the language it parses have been inspired by Graphviz Dot, which provides a really good way to document State Transition Diagrams, data structures and directed graphs. Unlike Graphviz, this program does no clever layout operations or spline routing as this is not needed for MSCs, and so was much simpler to implement. Doxygen (version 1.5.2 onwards) also allows MSCs to be embedded directly in the same way that dot diagrams can be added to documentation, making it easy to improve Doxygen generated documentation through the use of message sequence charts.

Mermaid, as a text-based diagramming tool allows for quick and easy updates, it can also be made part of production scripts (and other pieces of code), to make documentation much easier. Mermaid is a Diagramming tool for everyone. For the sake of completeness, here's another free, web browser based option: SequenceDiagram.org is an online tool / software for creating uml sequence diagrams. All processing of parsing and painting the diagram is done client side in the user's web browser.


The following are examples of the raw input code and output that is generated, in this case as a PNG.

Description of Mscgen Language

The general format for a message sequence chart is given by the following annotated example. It should be noted that whitespace and newlines are ignored by the input parser.

Input fragmentMeaning
Comment. Lines starting with # or // are ignored, as a C-style comments wrapped in /* and */
Starts the MSC
Output control options, in this case, set the output image width to 800 pixels. Note that the hscale option could be used to specify a scale factor for the width instead of an absolute, if preferred.
Lists the entities that will be used in the message sequence chart, in the order in which they should appear left to right and horizontally across the page. Note that each entity name can or may not be quoted, unless the name is to include a space, in which case double quotes are required.
Indicates that some message is passed from a to b. Both of the named entities, in this case a and b must have been declared at the start of the message sequence chart. Again, if an entity name contains spaces, double quotes should be used.
Indicates that some message is passed from c to a. In this case some attributes are also supplied in square brackets. The label attribute supplies text that is written above the message arc.
This shows the end of the Message Sequence Chart

The syntax is very simple. The important part to notice is that the first lines give the message sequence chart options and entities, with each of the following lines describing a message arc. The following table shows each of the possible message arc types, including the so-called 'special' arcs that do not show a relation between entities but instead describe something horizontally on the chart.

GraphicSource RepresentationMeaning
-> or <-
=> or <=
Method or function call
>> or <<
Method or function return value
=>> or <<=
:> or <:
Emphasised Message
-x or x-
Lost Message
Indicates that some signals may be deliberately omitted from the msc, or that some large period of time may have passed.
Used to add comment to a block of signals or indicate some action or state has occurred.
Used to add extra space between rows.
->* or *<-
Broadcast arcs, where the arc is extended to all but the source entity. Any arc label is centred across the whole chart.
Box arcs, where the arc is replaced with a box between the selected entities. Any arc label is centred in the box and word wrapped if needed.
Rounded box arcs, where the arc is replaced with a box between the selected entities. Any arc label is centred in the box and word wrapped if needed.
Angular box arcs, where the arc is replaced with a box between the selected entities. Any arc label is centred in the box and word wrapped if needed.
Note box arcs, where the arc is replaced with a box between the selected entities. Any arc label is centred in the box and word wrapped if needed.

The box types allow state and condition boxes to be added. In the source these are still represented as a relation between entities, but in this case the box is made to span from the source to the destination entitiy.

In addition to the arc types, a small number of attributes can be given to each message arc or entity. These attributes are placed in square brackets as a coma separated immediately after the entity name or message arc to which the attribute is to be attached:

The following table describes all of the possible attributes and their meaning, noting that each of the attributes can be specified for the special '..' and '---' arc types, as well as any other arc or entity. Road traffic management system.

Source AttributeMeaning
labelA label to place on the message arc, or label to use for an entity. This is reproduced literally above the message arc or in place of the entity name. When used as a message arc label this may also contain parameters or required text. If a n is encountered, it will be interpreted as a newline, placing text below the arc as well as above it in the normal position, or expanding entity tiles onto more lines.
URLWhen generating the image, colour the label in blue. If generating an image map, create an entry for the label to the specified URL. If the message sequence chart is to be embedded in Doxygen documentation, the URL maybe specified as ref xxx where xxx is the name of some documented element; in this case a link to the element will automatically be made.
IDAdds a superscript identifier to the label. Typically this maybe a number such that specific elements can be identified and referred to in surrounding descriptive text.
IDURLSimilar to the URL attribute, but links from the ID text rather than the message label. This has the same semantics as the URL attribute, but is only of use if an arc also has an ID.
arcskipThis offsets the vertical position at which an arc reaches its destination entity.
linecolour, linecolorFor arcs or entities, set the line to the specified colour.
textcolour, textcolorFor arcs or entities, set label text to the specified colour.
textbgcolour, textbgcolorFor arcs or entities, set a colour for the text background block. Sets the fill colour for 'box', 'abox', 'rbox' and 'note' shapes.
arclinecolour, arclinecolorOnly meaningful on a entity, this sets the default line colour for all arcs that originating from that entity. This can be overridden by linecolour attributes on specific arcs as desired.
arctextcolour, arctextcolorOnly meaningful on a entity, this sets the default text colour for all arcs that originating from that entity. This can be overridden by textcolour attributes on specific arcs as desired.
arctextbgcolour, arctextbgcolorOnly meaningful on a entity, this sets the default colour for the text background for all arc oriniationg from that entity. This can be overridden by textbgcolour attributes on specific arcs as desired.

Colours can be specified either as RGB colour codes using a # prefix as per HTML markup, or can use one of some predefined colour names as given in the following examples.

white #ffffff
silver #c0c0c0
gray #808080
black #000000
maroon #800000
red #ff0000
orange #ffb000
yellow #ffff00
olive #808000
aqua #00ffff
teal #008080
blue #0000ff
navy #000080
indigo #440088
purple #800080
violet #d02090
fuchsia #ff00ff

Finally options can be added to the input file to control various aspects of the generated image. At present only a few options are supported and must be given at the top of the input file as in the following example. The allowable options are described in the table.

hscaleScale the image width by this factor, which must be a non-zero value. Normally the output width is 600 pixels for a PNG, but can be scaled to any value by specifying fractional multipliers. For example, specifying a value of 1.5 would set the width to 600 x 1.5 = 900 pixels.
widthSet the image width to this values, which must be non-zero and is given in pixels. This can be used instead of the hscale option, in cases where the explicit image width is preferred to a scale factor.
arcgradientThis causes message arcs to slope down the page rather than running horizontally. The value given is the number of pixels below the start of the message arc that the end of the arc should meet the target entity.
wordwraparcsIf set to 'true', 'on' or '1', this will cause long lines of text on arrow arcs to be automatically word wrapped. By default word wrapping is only enabled for 'box', 'abox', 'rbox' and 'note' style arcs.

The grammar for the mscgen language can be seen here.

The Software

Mscgen is licenced under the GPLv2. This covers use of the program sources but places no restriction on the usage of the tool itself or the diagrams it produces. Mscgen is written in ANSI-C, and uses the GD graphics library for PNG output.

Mscgen can be built under Linux, Cygwin, and as a native Win32 application through Cygwin with the wonderful -mno-cygwin compile option. Since version 0.17 it uses autoconf/automake, so should be reasonably automatic in building provided that the dependent packages (gcc, flex, bison, libgd-devel) are avaialble. Others have previously reported success building the sources SunOS 5.8, Solaris 10, FreeBSD as well as Mac OS X.

Sequence Of Events Chart


The current version is 0.20 (changelog). The latest version of the software can be downloaded from the following links:

Sequence Chart Pdf

mscgen_0.20.exea04b258bb459f894ed8ec2c7896fa346Windows installer (369KB)
mscgen-w32-0.20.zip3af8a07455d6fb98d758001ec4c02cd4Windows binary (398KB)
mscgen-0.20.tar.gzb1b4266ed2b1e7c6df1dff3d2530a0b0Linux dynamic binary (46KB)
mscgen-static-0.20.tar.gz49381a5897a7992a1b8c0fd7cbc2f9f7Linux static linked binary (437KB)
mscgen-src-0.20.tar.gz65c90fb5150d7176b65b793f0faa7377Source package (201KB)

RPMs and Yum

RPMs built for various Fedora versions and EPEL are available at http://www.mcternan.me.uk/mscgen/yum/. You can either install these RPMs directly, or you can install a repository for getting mscgen and future updates:

Fedora RPMs are signed with my public key, and yum should prompt you to import this key once the repo is installed. Because of differences in signing for EPEL and Fedora, the EPEL packages are not currently signed.

Development Sources

The development sources are also available on Google Code, and can be browsed online or retrieved using anonymous SVN access.

New releases are announced via a Google Groups announcement mailing list. This carries only release announcements and you can subscribe through the following form:


Bugs, patches, and suggestions can either be emailed directly to me, or entered into the Google Code issue tracker. Since this is hobby project it can take a long time for me to respond, but I try to review every patch and respond to all emails.

Doxygen Integration

Initially I made custom modifications to Doxygen such that it could call other tools in response to a new command keyword. In response to this Doxygen version 1.5.2 (released 4-4-2007) was enhanced by Dimitri to support the msc and endmsc commands. This means that the following markup can be used to add MSCs to Doxygen documentation:

The output from this sample can be seen here. Another example of using this command is also given in the Doxygen manual.


Install Packages

Some kind people have packaged Mscgen for a couple of Linux distributions and environments:

Story Sequence Chart

  • Cygwin: Cygwin packages, installed using the Cygwin setup.exe.
  • Ubuntu: Deb packages which can be installed using apt.
  • Debian: Mscgen packages on packages.debian.org.
  • OpenSuse: Package page in openSUSE Build Service.
  • Gentoo: ebuild.
  • FreeBSD: Mscgen port at FreshPorts.org.

Integration with other Tools

  • AsciiDoc
    Henrik Maier has kindly developed a filter for Mscgen at http://code.google.com/p/asciidoc-mscgen-filter/.
  • Doxygen
    Supported by the msc and endmsc tags since Doxygen version 1.5.2.
  • Sphinx (Python documentation generator)
    Leandro Lucarella has contributed an extension for Sphinx to allow MSCs to be included in Python documentation. This package can be found at http://pypi.python.org/pypi/sphinxcontrib-mscgen.
  • Msctexen (LaTeX Integration)
    Andrzej Lichnerowicz has produced a package to allow inlining of mscgen MSCs within LaTeX documents. The project is open source and hosted at github.
  • Org-Mode (an Emacs Mode for Notes, Project Planning, and Authoring).
    This Babel package includes support for Mscgen graphs, see their documentation for details.
  • Pkgsrc
    Jan Danielsson has kindly added Mscgen to pkgsrc.
  • TWiki
    Antti Haapakangas has created a plugin for TWiki to allow embedding of MSCs.
  • JIRA
    Addteq kindly produced a plugin for JIRA which is available at the Atlassian marketplace.
This page is maintained by Michael McTernan