Using this website

Here you will learn everything about using the Sympathetic Resonances site. Don't let the page size intimidate you, the Getting started section only takes about 2-3 minutes to read.

You may want to keep this page open while working in another browser tab.

Table of contents

Getting started

Signing up

In order to store your own mbira pieces, please register as a user. Click on the "Login" button at the menu bar in the upper right corner, and choose "Sign up".
After completing the registration form, you will receive an email with a confirmation link. Please check the spam folder of your email account, too! The link will take you to the login screen, which can also be reached from the Login menu.

User profile and privacy

The signup form asks for a few personal details, your name, email address, city, and country. User accounts are tied to a single email address - you cannot register twice with the same email.
No personal information is ever disclosed to unregistered visitors of the website. Your email address is never shown to anyone who does not yet know it, unless you use the website to send a email notifications on your behalf, which fills in your reply address.

Your name is shown to other registered users on a few occasions:

Aliases
If you prefer your name not to be shown to other users, fill in the Alias field. The alias is shown instead of your name throughout the website (unless when sending emails on your behalf).

Aliases may also make you more recognizable, e.g. as a member of an organization, or if there is another user of the same or similar name.

Browsing pieces

Logging in, or clicking the “Your Pieces” button in the menu bar gets you to your personal archive.
At the top of this page there is a drop-down list to select the instrument type, and a search box.

The rest of the page shows up to four lists for the selected instrument: Piece templates, your own pieces (if any), pieces others shared with you (if any), and pieces shared with all users. Click on a piece's name to open it (e.g. "Nhemamusasa").

Searching pieces

Type in one or more search terms and hit the Search button or Enter key to show only pieces matching the terms. Press the Clear button to again show all pieces.
In case of multiple search terms, only pieces are shown which contain all of them, like "kari" and "pfu" in the picture above.

The search covers all bits of text in the entire piece record, including headings and comments of the parts themselves. Using some naming scheme, like the one from Paul Berliner's The Art of Mbira book, you can quickly search for individual parts:

  ↔   

Viewing pieces

Each piece page has two sections: Metadata at the top, and a list of musical parts underneath. Empty metadata fields are hidden until you press "▶ Show all fields".

Playback

You can audition a part with the ► (Play) button. Usually playback starts at the beginning of the part, but you can start at any other point.
The ■ (Stop) button stops all playback.
Press the "+" button to play another part simultaneously.
Press the "-" button to stop a single part while keeping the others running.
This way you can play back any combination of parts.
Restart audio after changes
When you press the ► button, the web server synthesizes an audio file from the part and streams it to your browser. Therefore, after editing a pattern, you must stop and restart playback to hear your changes.
Generating a fresh audio file
Subsequent playbacks of an unchanged part re-use the audio file. On rare occasions something might go wrong, and the audio file would not sound as expected. Hold the Shift/⇧ key while clicking on ► or "+" to make the server generate an fresh audio file.

Choosing playback sound

Pick the playback instrument from the dropdown list next to the play buttons:
The lower part of the list shows all available sampled instruments.
Click the ⓘ icon right of the list box for details about the selected instrument.
Instrument reference key
Each line starts with the pitch on the chromatic scale closest to the instrument's "reference key". The reference key is an arbitrary choice, simply to have a reference for comparing instruments' relative pitches.

In general, the lowest key on the instrument is picked as the reference. Otherwise another prominent key, which is then mentioned in the notations section.

Choosing your preferred tuning
The three ‘Preference’ entries at the top are placeholders which you can personalize in order to play all content in your preferred tuning.

Public pieces use Preference 1 for Kushaura parts, #2 for Kutsinhira parts, and #3 for occasional third parts.

It is best to follow this convention in your own pieces, unless a part requires a particular instrument.

Playback tempo

The current playback tempo can be determined (and stored per piece) in the according field:
The tempo is specified in PPM (pulses per minute). With three pulses per beat, 300 PPM equals 100 BPM (beats per minute).

If you leave this field empty, the instrument type's default tempo is used (e.g. 240 PPM for an mbira). In a later version of the app the default tempo will be a user preference, so unless you see a good reason for pinpointing a specific tempo, just leave the the field empty when storing pieces.

For playback and rehearsal just temporarily change the tempo of any piece as you like.

Visualization

Click the button to show an animated picture of the instrument.
Click on the image to toggle colors which indicate the keys' pitch classes. Drag the handle in the lower right corner to resize the animation. Try it right here:
 
Non-existent keys
If a piece contains notes for which there is no key in the "virtual mbira" picture, a key label is shown instead, roughly at the position where the respective key would sit.
This njari lacks an LI4 key. It would be
a green key right below the blue LI5.
The label also shows when that key is triggered.
Hints

Using another notation

If you have used tabular mbira transcriptions before, the tables may look familiar, but perhaps you wonder about the numbers. The example pieces use the numbers 1-7 to enumerate the seven pitch classes (scale degrees) in each register. This notation is called Pitch.

You can translate the piece to another notation by selecting a Translator from the "Other Notations" section and pressing the “Translate Now” button.

Choose “Pitch → Position” to translate the piece into a more widespread notation where the keys are enumerated according to their position within each manual.

Hint: Don't hesitate to experiment with the translators or any other feature. All changes are temporary unless a piece is saved. The translator mechanism can also be used to transform pieces in interesting ways, like transposing them or translating them to another type of instrument.

Editing mbira parts

Creating a new piece

Click again on “Your Pieces” at the menu bar, to get to your list of pieces, then on "Create Empty Piece" in the Template Pieces section. This section contains templates which will automatically be copied before editing.
At the bottom of the page is a single empty part:
Choose your preferred notation from the 'Notation' listbox. For mbira dzavadzimu pieces, Position is a widespread beginner's notation, which numbers keys by their position in each manual.
Hint (matepe/madhebhe/hera pieces): Even though there are no notes yet, you may have to translate the piece to the desired notation in order to get the correct row labels in the table.

Hint: If the table is wider than your browser window or screen, you can make editing easier by shrinking the browser’s font size.

Editor buttons

In order to keep the user interface tidy, most editing controls are hidden at first. Click anywhere on the table to reveal them:
↓

Editing and selecting cells

Let’s first look at the tabular section in the lower half. It works a bit like a spreadsheet app. Click on an empty cell, type “Hi” and press the Enter key:
If you want to change the text, press Enter to toggle between the table and the input field. On a touch screen, double tap a cell to edit its value (or tap on the input field).

Hit the Delete key to delete the selected cell(s).

Move the cursor with the arrow keys. Hold Shift/⇧ when pressing the arrow keys or clicking to select a rectangular area.

The ⌘/Ctrl+A shortcut selects all notes.
You can also select multiple cells individually by holding the Ctrl/⌘ key and clicking with the mouse.
Entering or deleting values always affects all selected cells:
Clicking the cursor again (but not as fast as a double click) selects a note cell's column ...
or a caption cell's row of notes.
Playback start and selection
While editing the table, press the Space bar to start playback from the (leftmost) selected column, regardless of any playback start point preference.

When you click the play button and only the cursor is visible, then playback starts at the beginning of the part. As soon as more than one cell is selected, the playback starts at the leftmost selected column.

This allows you to start playback at any point on a touchscreen, too, by clicking a column twice before hitting the Play button.

Cut, Copy, Paste, Duplicate

Inside a table, use these shortcuts for familiar clipboard and editing operations.

Note: There are a couple of limitations for different browsers:

But don't worry, if the keyboard shortcuts do not work in your browser, there is a simple workaround.

Command MacOS shortcut Windows shortcut
Cut ⌘X Ctrl+X
Copy ⌘C Ctrl+C
Paste ⌘V Ctrl+V
Paste (overwrite all) ⇧⌘V Shift+Ctrl+V
Duplicate ⌘D Ctrl+D
Duplicate (overwrite all) ⇧⌘D Shift+Ctrl+D
Select All ⌘A Ctrl+A

The difference betwenn the regular and the "overwrite all" Paste and Duplicate commands is that the former only pastes notes from the clipboard, while the latter also pastes empty cells, thus overwriting the entire target area:

Duplicate:

→

Duplicate (overwrite all):

→

Copying notes from/to another piece or spreadsheet

The Cut and Copy commands copy notes into your computer's clipboard. You can paste them into any other part, even between browser tabs.

You can also copy & paste table data from spreadsheet software like Microsoft Excel, Apple Numbers and Google Sheets.


Copy ↕ Paste

The clipboard data is in TSV format, a simple way to exchange tables as text, where each row becomes a line, and cells in each line are separated by a Tab character.

You can already see this data in the input field whenever multiple cells are selected. Copying and pasting data from or to the input field has the same effect as in the table itself.

Workaround for clipboard commands in all browsers
Since the input field always reflects the selected data in the table, you can use this simple method as a workaround if your browser does not support the Copy/Paste keyboard shortcuts:

Whenever you would normally press ⌘/Ctrl+X, C or V, press the Enter key first, then ⌘/Ctrl+X, C or V, and then Enter again.

This moves the focus to the input field and back to the table, and directs the clipboard command to the input field.

Cell details

Besides the display text, each cell can also store additional information. Simply select a cell, and type a note into the details field:
Shift + Enter toggles between the table and the details field. A little triangle indicates the presence of details.

Changing the number of rows or columns

So far we were only editing the content of the table. To change the number of columns (pulses) or rows (tracks), use the buttons with an arrow label.
There are four actions with can be equally applied to create and delete columns (→ ←) or rows (↓ ↑). Just try out all the buttons and you will quickly get an idea.

Shifting the pattern to a different starting point

The “Shift ← →” button shift the selected rows cyclically left or right. To shift the whole part, click a cell twice to select all rows:
↓
To shift just a single row, e.g. the Hosho downbeat to the left, just click into the row and press “←”:
↓
To shift the pattern by more than one pulse, select the respective number of pulses in the desired rows. You can do this very visually: For example, to move the 15 to where the 5 is, select the range from 5 to just before 15 and press "←". This works similar to deleting the columns .
↓
The selection is then retained, so that you can move the pattern back with "→", and by pressing again move the 5 to where the 15 was before.
↓

Part layout

The “Layout” field next to the footnote determines the table's layout.
“12 12 12 12 page” means that the table contains four sections which 12 pulses each, and in case there are more pulses than 48, a new “page” of four sections is started. Currently, "page" has no visual effect, and the numbers result in a little thicker division line between the cells every 12 pulses. In the future the may be more advanced layouts.

Table contents

You can put any text into table cells. When playing back parts, only valid combination of row captions and cells (e.g. RT and 3) are considered, everything else is ignored.
Lyrics and free form content
When translating the piece to another notation, invalid combinations of captions and cells are marked as not translatable. To avoid this and keep free form information (like lyrics) in place across translation, use tracks with empty captions at the bottom of the table:

Managing multiple parts

Heading and comments

A piece’s page may contain any number of parts (somewhat limited by the increasing loading times of the page). Each part has heading and comments fields for additional information.

It’s a good idea to put some description into the Heading field which uniquely identifies it in the context of the piece. Headings e.g. show up in the background menu.

Use the comment field for any additional information about the part:

The part list

Use the “Add Part” button on the right hand side to create a new, empty part underneath the current one.
“Duplicate" adds a copy, and “Remove" deletes the part from the list.

Unfortunately there is not (yet) an Undo function. Use the “Remove” function with care, and save the piece often, ideally after finishing every single part!

The Arrow up/down buttons change the position of the part in the list and exchange it with its upper or lower neighbor.

The moved part remains within the view, but sometimes this is not obvious unless you keep an eye on the position of the browser’s scroll bar.

Parts in the background of another

Parts can be shown in the background of another: All empty cells of the foreground part let the background shine through in a lighter color. You can stack up any number of layers. Simply select a background part from the dropdown box in the upper right of the part:
If the background part is shorter than the foreground, it is looped horizontally to fill up the number of pulses in the foreground.

Backgrounds are really useful to transcribe variations since only the changes need to be noted. By changing the background you can also quickly try out the same variation on different parts.

An underscore (“_”) indicates an omission of the background note. Cell details of background parts are also showing through. An underscore in the details field stops them from being shown in above layers.

Hint: When transcribing variations, it's generally a good practice to use a separate part for all notes which are meant to be played together. If there are many single-note variations, you can also put them into a single part and add a comment that can be played independently.

Merging and subtracting parts

The “Merge” button next to the background box merges all background notes into the foreground, i.e. all white notes become black.
Conversely, the “Subtract” button removes all notes from the foreground, which are equally present in both, foreground and background.

Saving & duplicating pieces

Saving new pieces

You can save a new piece with the button at the very bottom of the page, or drop it with the "Exit Without Saving" button - or by simply closing the browser tab.

Hint: No changes or additions become permanent until a Save button is hit, therefore it is good to save early and often.

Before saving a new piece you should give it a proper name, so you can locate it in the overview, and select the instrument and the used notation from the respective drop-down lists.
These settings are used to inform playback and translation, changing them has no effect on the numbers in the tables. Only translation changes the actual numbers (and can usually be reversed).

Saving existing pieces

Once a new piece is saved, you will see a different set of buttons at the bottom of the page.

Use "Save & Exit" to save changes and return to the list of your pieces.

Hit "Save" to save the piece on the server, and continue editing.
Duplicate pieces with the "Save As New Piece" button. The saved original remains unchanged, and the current state will be saved as a new piece.
"Exit Without Saving" simply returns to your list of pieces, without saving any changes you have made since opening the piece.
Hint: To discard any temporary or accidental changes to a piece and revert to its saved state, just use the browser's Reload button.

Checking a piece for typos

After you saved a new piece, you may want to check it for typos. Occasionally right numbers end up in the wrong row, so it is a good idea to do these checks routinely.

The simplest way to check a piece against a notation is to translate it to another (equivalent) notation, and then back. The translation process adds [UNTRANSLATED] details to every cell it cannot translate.

Since you just want to see this error indication, and not save the piece in this state, it is best to open the same piece in two browser tabs. In the first tab you fix possible mistakes and later save the original piece, in the second tab you conduct the double translation and just close the tab when you are done.

Sharing pieces

To share a piece with other users, click on "Share" in the overview list.
In the subsequent dialog, enter the recipients' email addresses. If you are connected with other users by means of sharing pieces or group membership, you can pick them from a dropdown above the Email address(es) field.
Choose whether a notification email should be sent and optionally enter a message. Check the Invite new users box to send an invitation email to recipients who are not yet registered as users.

Finally determine whether they may only read or also edit the shared piece. You can still change this later by sharing the piece again with different settings.

Transforming pieces

Besides employing a different notation, the translator menu offers other options to transform a piece.

Transposition

You can transpose a piece up or down by 1-3 scale degrees. Choose a translator from the "Transposition" section, and press the "Translate Now" button.

(Note: This currently work only with the mbira dzavadzimu in Pitch notation, or matepe/madhebhe/hera in Pitch.4 notation. If you are using another notation, first translate to these notations, then transpose, then translate back to your preferred notation.)

Two methods for transposition are available, "Shift" and "Cycle".

Automatic transposition does not always deliver the most playable or musically satisfying results, but should provide a reasonable starting point for quick exploration and manual post-editing.

Sometimes more than one note ends up in the same playing area (see the "L" track in the picture below). This is no problem for the playback machinery, but impossible to play with one finger, so you may have to make the choices that the translator cannot provide.

Hint: Avoid repeated transposition. Rather start over with the original piece and a wider interval. In certain cases, multiple notes are mapped to the same target which changes intervals (e.g. the missing B2, key is substituted by B1 when shifting downwards).

Translating pieces to another instrument type

You can translate a piece to another instrument by choosing a translator from the "Other Instruments" section, and pressing the "Translate Now" button.
As of today, you can translate As instrument types differ in key layout, playing techniques and composition styles, sometimes more than one note may end up in the same playing area as the result of the automatic translation. Nonetheless it is a good starting point for exploration and manual post-editing.

Piece metadata

The form field in the metadata section at the top of a piece page should be by and large self-explanatory. Let's look at the non-obvious bits:

Alternative name(s)

The Alternative Name(s) section is meant to list alternative names of the piece, one name per field. Use the and buttons to add and remove fields.
If you paste URLs (hyperlinks) into the Medium Details, Where, Source Details, Lyrics, or Notes fields, they will appear as clickable links below the respective field after you have saved the piece:
    

For links to images, the image appears embedded into the page, if a common image file extension is detected within the URL (otherwise use this format). Likewise for audio files (wav, mp3, ogg).

Links to videos on Youtube, VideoPress (including video.wordpress.com), and Vimeo videos appear embedded into the page. You can also embed the SoundCloud audio player using the shorthand format below.

If you want links to be shown with a text, or media players to have a title, enclose title and link (in this order) with double brackets:

[[My link to Wikipedia https://wikipedia.com]]

will be shown as

My link to Wikipedia

Shorthand for embedding videos and SoundCloud tracks
Instead of with a URL, you can also embed embed media players like this:

[[My Youtube video YOUTUBE:11KXsY2ZMM0]]
[[My VideoPress video VIDEOPRESS:Hp6Rgzuh]]
[[My Vimeo video VIMEO:176602346]]
[[My SoundCloud song SOUNDCLOUD:278804666]]

The digit/letter sequences behind the colon are the video or track IDs. You will find them in link or code when sharing the video or audio track [for embedding] on the respective platforms. It is that section of the sharing link or code which differs when sharing two different media items.

This format is also the only way to embed SoundCloud tracks, as links to a song page do not contain the actual track ID.

Media start times
Playback start times specified in Youtube or Vimeo links are passed to the embedded media players. In the shorthand format, specify start times like this:

[[YOUTUBE:11KXsY2ZMM0@90]] (Start at 90secs)
[[VIDEOPRESS:11KXsY2ZMM0@75]] (Start at 75secs)
[[VIMEO:176602346@1m30s]] (Start at 1min 30secs)

Note the slightly different format for Vimeo.

Embedded Soundcloud players do not accept start times.

Embedding images
To embed an image on a page, you can just paste the URL that ends with a valid image file extension. You can add a caption:

[[My image description https://upload.wikimedia.org/wikipedia/commons/5/5b/Mbira_dzavadzimu_1.jpg]]

For URLs without a typical extension, or for images that are already hosted on the website and have a relative URL, use the IMAGE: prefix.

[[My image description IMAGE:/static/images/gallery/TIC_129_Mana_embudzi/0.JPG]]

Embedding audio files
Embedding audio works exactly like embedding images. For common files extensions (.mp3 .wav .ogg) just paste the URL, otherwise use the AUDIO: prefix:

[[A major chord AUDIO:https://upload.wikimedia.org/wikipedia/commons/6/6f/Dur_jm.ogg]]

There's currently no way to upload media. They need to be hosted elsewhere, e.g. on WordPress, Google Groups, Dropbox, or archive.org. If you want your image(s) to be hosted on this site, which makes sense if they are part of public pieces, get in touch.

Preferences

Open the preferences page via the User menu in the top right corner.

Playback instruments

In the Instruments section you can choose you preferred playback instruments for each instrument type.
Press the Save Instruments button at the bottom of the list to update your preferences.

Playback start point

Use this setting to determine where audio playback of a piece starts.
Press Save Playback Settings after changing the setting.

The Play button icons on the piece pages reflect this setting. Refresh browser tabs which are already open to update the setting.

With any of these options, it is still possible to start playback at any desired point by means of selection.

Hosho volume

This option determines the volume of the Hosho shaker sound.
Press Save Playback Settings after changing the setting. Refresh browser tabs with are already open for changes to take effect.

Notations

A notation is a set of names for the keys of an instrument. This website supports different notations for most instruments, and users can translate their transcriptions to any other notation with a few clicks.

Key names have two parts: The row label and the cell content. In the picture below the cursor sits in a row RT on a cell with a 1. Both components are required to identify the key, so the full key name in the notation is RT1.

Key Aliases

Sometimes the same key can be played with different fingers, often to maintain a motor pattern for the player. We want to able to reflect this in transcriptions in a way that is compatible with translation of pieces to other notations. Therefore, the same key can have multiple names, and can possibly be referred to in different rows (if rows represent different fingers or playing areas).

For instance, on the mbira dzavadzimu the right thumb occasionally plays the RI3-5 keys or even the L1 key. The RI3 can also be referred to as RT3'. (The names in this example are in Pitch notation.) The naming scheme for key aliases is different for each notation, and listed below.

If you miss a specific alias for your transcriptions, please let me know.

Notation Reference