Phyphox file format¶

There is a visual editor for this

Experiment configurations do not have to be written by hand. The phyphox experiment editor assembles them from blocks in the browser and generates a QR code to get the result onto a phone. The pages here describe the format it writes, which is what you need if you want control over details the editor does not expose — or if you simply prefer a text editor.

This page is highly technical and meant for advanced users who want to control every minute detail of their experiment. On this page you will learn how the phyphox file format works and how to create a phyphox experiment - all you need is a text editor. Some experience with the XML format is recommended.

Structure¶

The phyphox format is based on XML. The entire experiment is encapsulated within a phyphox root tag. Within this block, there are multiple blocks which define data-containers, inputs, outputs, translations, analysis etc.

Elements from a foreign XML namespace — any namespace other than the one of the root element, which is usually none — are ignored along with their entire content. This allows tools like experiment editors to embed their own metadata in an experiment file without breaking it for the apps. Elements in the file's own namespace remain strictly checked: an unknown element name is an error and the file will not load.

Attribute values are checked when the file is loaded: an enumerated value outside its allowed set, an unparseable color, a boolean other than true or false (all matched case-insensitively) and a value that does not parse as a number where one is expected are errors, and the file will not load. An unknown attribute name, on the other hand, is silently ignored, in any namespace including none — files carrying stale or misspelled attributes load, for compatibility with the many configurations in circulation that rely on it. The format validators still flag unknown attributes, so typos are caught at authoring time rather than silently changing an experiment. Attributes from a foreign namespace are ignored like foreign elements are.

Block: phyphox¶

The entire experiment is defined within the phyphox block. Its most important attribute is the version of the file format - not the version of the app. If the file format changes in a future version, this version number will increase. If phyphox (the app) encounters a file version newer than what it can read, it will not load the file but ask the user to update the app.

<phyphox version="STRING" locale="STRING" isLink="BOOLEAN">
    <title>TEXT</title>
    <state-title>TEXT</state-title>
    <category>TEXT</category>
    <icon>TEXT</icon>
    <color>TEXT</color>
    <description>TEXT</description>
    <link>TEXT</link>
    <translations>...</translations>
    <data-containers>...</data-containers>
    <input>...</input>
    <output>...</output>
    <analysis>...</analysis>
    <views>...</views>
    <export>...</export>
    <network>...</network>
    <events>...</events>
</phyphox>

Attributes

version: File format version as major.minor. An app refuses a file declaring a version newer than it supports, which is what gates every feature added to the format.; required
locale: Language the strings outside the translations block are written in. Without it they are assumed to be English.; optional
isLink: Marks an entry that is not a runnable experiment but a redirect: opening it - from the collection, a URL, a QR code or a shared file - sends the user to the page named by its link rather than opening an experiment.; added in 1.13 optional, boolean, default: false

Tag: title¶

The title of the experiment. This is just a simple string. Try to keep it short and concise.

<title>TEXT</title>

Text content: The title. Keep it short.

Tag: state-title¶added in 1.5

This should not be used for an experiment which will be distributed. This tag contains the title given by the user when saving the state of an experiment. If this is set, the app will show this experiment in the saved-states section. A file may carry at most one state-title — like the other metadata tags of the root element, it must not be repeated. If a legacy file nevertheless carries a duplicate (old versions of the app could write one when re-saving a state), the app tolerates it and the last occurrence wins.

<state-title>TEXT</state-title>

Text content: The saved-state title.

Tag: category¶

The category of the experiment. This is just a simple string used by the app to group the experiments. Try to keep it short and concise.

Note that this can and should be translated if you use translations (see below) as the app uses the localized version of this string and cannot match your experiment to the default group if the category is given in a different language.

<category>TEXT</category>

Text content: The category name.

Tag: icon¶

The icon of the experiment. We recommend a small PNG with few colors; there are various web-based tools to create a base64-encoded PNG from a PNG file.

<icon format="STRING">TEXT</icon>

Text content: Up to three characters, or a base64-encoded image.

Attributes

format: Controls whether the element's text is interpreted as a string or as a base64-encoded image. From a string phyphox takes the first three characters - fewer is fine - and draws a simple icon with them. A base64 image is decoded and displayed; a small PNG with few colors works best.; optional, one of string, base64, default: string

Tag: color¶

The base color for the experiment. This is used as a background of the icon (if a text-based icon is used or if it has a transparent background) and for the label of the category. If a category contains experiments with different colors, the most common color is used.

Color can be defined as a 6-digit hex value or as one of the named Colors.

<color>TEXT</color>

Text content: A six-digit hex value or a named color.

Tag: description¶

A description of the experiment. The first line should be a very short summary of what the experiment does as this line will be shown in the experiment list. Any whitespace at the beginning and end of the description as well as in each line will be stripped.

<description>TEXT</description>

Text content: The description. Leading and trailing whitespace is stripped per line.

Tag: link¶

A link tag defines a link to some resource on the web. You may have multiple link tags in your phyphox file and each will be listed as a button under the experiment description. When the user pushes the button, they will be redirected to the URL (usually in a web browser, but it might be a specific app for a specific URL - for example, YouTube links usually open in the YouTube app on Android).

<link label="STRING" highlight="BOOLEAN">TEXT</link>

Text content: The URL. Must not be empty for a link at the root.

Attributes

label: The text on the button offered under the experiment description. The label also identifies the link: a link element inside the applied translation block matches it with an exact, case-sensitive comparison, and duplicate labels are an error. The button text is localised with the translation attribute of the translated link, never through the string mechanism.; required
highlight: If set to true, the link is also featured in the experiment menu. This is meant for especially relevant links such as instructions for the experiment; how a link is "highlighted" may change in later versions.; optional, boolean, default: false

Block: translations¶

The translations block may hold one or more translation (note: singular) blocks, describing the translations of strings shown to the user. Any string outside the translations block is considered to be in English and then translated to other languages from within the translations block, unless a different global language has been defined in the tag of the phyphox-block or English appears explicitly as a translation block. If English is used in a translation block and no language has been defined in the phyphox-block, the text outside the translation block should be treated as a placeholder.

Exactly one translation block is applied: the one whose locale best matches the user's locale. Where no block matches better than the file's base language, the base strings are used as they are. Blocks are never combined, so each translation block has to be complete in itself.

<phyphox version="...">
    <title>My experiment</title>
    <category>Example</category>
    ...
    <translations>
        <translation locale="de">
            <title>Mein Experiment</title>
            <category>Beispiel</category>
            <string original="Some string used in the experiment.">Ein im Experiment genutzter String.</string>
            ...
        </translation>
        <translation locale="fr">
            <title>Mon expérience</title>
            <category>Exemple</category>
            <string original="Some string used in the experiment.">Une chaîne de caractères utilisèe dans l'experiénce.</string>
            ...
        </translation>
    </translations>
    ...
</phyphox>

Block: translation¶

Each translation block holds all the translations for a single language.

Attributes

locale: Two-character ISO language code.; required

Tag: title¶

Localized version of the title tag in the phyphox-block (see above). If the user's locale matches the locale of the translation block, the title will be replaced by this entry.

<title>TEXT</title>

Text content: The translated title.

Tag: category¶

Localized version of the category tag in the phyphox-block (see above). If the user's locale matches the locale of the translation block, the category will be replaced by this entry. Note that phyphox will group experiments by the localized version of the category.

<category>TEXT</category>

Text content: The translated category.

Tag: description¶

Localized version of the description tag in the phyphox-block (see above). If the user's locale matches the locale of the translation block, the description will be replaced by this entry.

<description>TEXT</description>

Text content: The translated description.

Tag: link¶

This is the localized version of the link tag. The label identifies which link is meant: a link element carrying the label of a base link changes that link, one with a new label adds a link only shown in this language. The button text is localized with the translation attribute — the label itself always stays as written, since it is the key the two declarations are matched on. For example, if you link to a Demo video in English with

<link label="Demo">http://site.org/my/english/video</link>

you can point the button at a German version, with a German button text, in the translation block with

<link label="Demo" translation="Demo (deutsch)">http://site.org/my/german/video</link>

The URL may be left out to keep the original URL and only change the button text:

<link label="Demo" translation="Demo (deutsch)" />

And a link element with nothing but a label removes that link from this language:

<link label="Demo" />

<link label="STRING" translation="STRING" highlight="BOOLEAN">TEXT</link>

Text content: The URL. May be empty (after trimming) on a link that matches a base link, which keeps the base link's URL; empty on an unmatched label it is an error and the experiment will not load.

Attributes

label: The key this link is matched on - an exact, case-sensitive comparison with the base labels. Duplicate labels within one translation block are an error. For an added link, the label is also the displayed text unless translation is given.; required
translation: The displayed text of the link in this language. If absent, the label is displayed as written. This is the only way a link's button text is localised - link labels never pass through the string mechanism.; added in 1.20 optional
highlight: Feature the link in the experiment menu. Defaults to the replaced link's value, or to false for an added link.; optional, boolean

Tag: string¶

Use the string-tag to translate any string shown to the user besides the title, description or category. If the text of a label, view etc. matches the string given in original, phyphox will display the tag's text instead. Of course, this only applies if the user's locale matches the translation locale.

<string original="STRING">TEXT</string>

Text content: The translated text.

Attributes

original: The string to replace, exactly as written elsewhere in the file.; required

Block: data-containers¶

In data-containers all buffers are defined. Any input (sensors, microphone) writes to these buffers, any analysis module performs its operations on these buffers, the output modules read from these buffers and the results are shown to the user from these buffers. The buffers connect every module of the experiment.

<phyphox version="...">
    ...
    <data-containers>
        <container>Buffer 1</container>
        <container size="1000">Buffer 2</container>
        <container type="buffer">Buffer 3</container>
    </data-containers>
    ...
</phyphox>

Tag: container¶

The container tag defines the name of a single data container.

<container size="INTEGER" init="FLOATS" static="BOOLEAN" type="STRING"
           clearGroup="STRING">TEXT</container>

Text content: The buffer name, as referred to everywhere else.

Attributes

size: The size of the data container. For the buffer type this is the number of values the buffer can hold. A buffer is a queue of fixed length: new data is appended until it is full, and then old data is removed from the other end. Setting the size to zero makes the buffer infinite, which needs care - never keep filling an infinite buffer that is the base for complex analysis, as the load grows without bound as the experiment runs. An audio input recording into an infinite buffer is the extreme case: with append="true" the entire recording accumulates in memory at the full sample rate.; optional, integer, default: 1
init: If set, the buffer is initialized with the given value when the experiment is loaded and whenever the data is cleared. If not set, the buffer starts empty. Since file format 1.5 several values may be given, separated by commas, to initialize a buffer with more than one value.; optional, comma-separated floats
static: If set to true, the content of this buffer is only written once: an analysis module whose output buffers are all static executes a single time and is skipped from then on, which is the point of the attribute - saving the recomputation of values that do not depend on measured data. Because a skipped module no longer runs, it also stops consuming (clearing) its keep=false input buffers after that first execution. The user's clear-data action resets a static buffer to its init values and re-arms the writing module for one new execution - static data does not survive a user clear. (Lifecycle decided 2026-08-24.); optional, boolean, default: false
type: The only type supported right now is buffer. This attribute can be ignored for now, but other container types may be added in the future.; optional, one of buffer, default: buffer
clearGroup: If set, the buffer is not cleared automatically when the user presses the trash symbol. Instead the string assigned to clearGroup is offered as an option the user can select. This is particularly useful for settings or calibration data that should survive deleting the measurement. Several data containers can share a clearGroup, and the string can be translated - take care that translated names stay distinct, since it is the translated name that addresses the group. Assigning the special clearGroup "_" (a single underscore) means the buffer is never offered for clearing at all.; added in 1.20 optional, translatable

Block: input¶

The input block defines all hardware inputs such as sensors or the microphone used in the experiment. It is documented on a separate page.

Block: output¶

The output block defines all hardware outputs such as the speaker used in the experiment. It is documented on a separate page.

Block: analysis¶

The analysis block describes all the math required for the experiment. Its attributes and the rules common to all analysis modules are documented on a separate page. The modules themselves are listed by category:

Block: views¶

The views block describes the different layout groups (views) from which the user may choose to view the experiment data. It is documented on a separate page.

Each view can be built from individual view elements:

Block: export¶

The export block may hold one or more set blocks, grouping and naming multiple data-containers as a logical unit to be written to a file when the user wants to export the data. All sets are written on every export — the user only chooses the file format. Grouping for example the raw data and the analysis results into separate sets keeps them apart in the exported file.

<phyphox version="...">
    ...
    <export>
        <set name="Results">
            <data name="Frequency">frequency</data>
            <data name="Period">period</data>
        </set>
        <set name="Raw data">
            <data name="Time t (s)">accT</data>
            <data name="Acceleration x (m/s²)">accX</data>
            <data name="Acceleration y (m/s²)">accY</data>
            <data name="Acceleration z (m/s²)">accZ</data>
        </set>
    </export>
    ...
</phyphox>

Block: set¶

The set block will define a group of data-containers to be exported. The sets are represented in the final file: a CSV export results in a ZIP file containing a separate CSV file for each set, and an Excel export will contain a separate sheet for each set, in both cases named by the name attribute. The number of rows is determined by the set's longest column; shorter columns are padded with NaN for the missing entries.

Tag: data¶

Within each set, you can define multiple data entries. Each of them maps a data-container to a name displayed to the user.

<data name="STRING">TEXT</data>

Text content: Name of the data container to export.

Attributes

name: A name describing the data. This is usually the column title corresponding to the data in the exported file.; required

Block: network¶

The network block can define network connections that allow requesting values from or sending data to a service on a network (local or internet). It is documented on a separate page, covering:

Block: events¶

The events block was introduced with file format 1.12 (phyphox version 1.1.8) as a temporary solution to store event and time reference data. It will remain supported in the future to allow reading old experiment state files, but there will be no specific use for this feature once the experiment state is stored in a form that separates measured data (and events) from the phyphox configuration file.

The events block contains a list of event blocks with tags corresponding to any known event, which are currently start and pause. Each event needs to have an attribute experimentTime and an attribute systemTime giving the experiment time (seconds since first start, ignoring pauses) and the system time (milliseconds since 1970) of the event.

<phyphox version="...">
    ...
    <events>
        <start experimentTime="0.0" systemTime="1608126693705"/>
        <pause experimentTime="1.3307273210000001" systemTime="1608126695035"/>
        <start experimentTime="1.3307273210000001" systemTime="1608126696552"/>
        <pause experimentTime="2.310827263" systemTime="1608126697532"/>
        ...
    </events>
    ...
</phyphox>