## Documentation

Welcome to the documentation for ptcollab! Below you'll find some guides about how to use the software, as well as a list of features and tour of the UI. Click on a heading to expand it.

## For people new to pxtone

Background on pxtone
pxtone is a set of music creation tools made by Pixel, the creator of Cave Story and Kero Blaster. It includes two instrument editors, pxtone voice and pxtone noise, and a sequencer called pxtone collage. pxtone collab is a fan sequence editor that uses the audio engine source with a slightly different workflow, and also a few other features like network collaboration.
Getting started

To get started making music on your own, go to File > New to open up the New Session window. You don't have to change anything here.

Now, click the "+" on the left side in the "Voices" tab to load some instruments. Some sample instruments / voices are included with the program.

With the instruments loaded, you can create units for each instrument by going to the "Units" tab and pressing the "+" button. Each unit can play one instrument at a time.

Once you have your units, you can start putting notes down in the piano roll!

More pxtone concepts

Once you’ve played around drawing a few tunes, you might be interested in some of the other things you can change in the editor.

#### Unit parameters

Under the piano roll, there’s a panel called the parameter editor that you can draw in to change different aspects of how a unit sounds.

The dropdown on the left changes which parameter you’re changing. Here’s a brief description of each option:

- Velocity - how loud is each note?
- Pan (volume) - how loud is the unit on the left vs. the right?
- Pan (time) - how much should one side have compared to the other?
- Volume - how loud is the unit as a whole? This can also be used to change note volume while the note’s playing.
- Portamento length - how long should a pitch slide take? This can be useful for vibrato. (see “How do I…?” for more info about portamento)
- Fine-tune - should the unit be tuned sharp or flat?
- Voice - what voice should play the unit?
- Group - what effects should be associated with the unit? (See below for more info about effect groups)

#### Effects

pxtone lets you apply 2 additional kinds of post-processing effects to groups of units. These effects are delay and overdrive, and in ptcollab, they can be set up in the Song tab. You can double click a cell to edit it.

Delay is a kind of echo. The ratio determines how loud each echo is compared to the last, and the frequency is how close together in time each echo is.

Overdrive is a way to amplify sounds and also cut amplitudes above a threshold. It can lead to some nice distortion effects!

More detail about these effects are here.

Groups are used to apply effects to units. This is the G tab in the effect panel. Take this example:

Which applies an echo to every unit in group 1. You can make a unit a part of the group by changing the group parameter at the bottom.

## For pxtone collage users

Workflow differences
ptcollab tries to have a similar workflow to pxtone collage. Besides hosting / connection, some notable differences are:

- Select with Ctrl+Shift+Click and Ctrl+A; Ctrl+D deselects. This replaces the selection ribbon in ptcollage.
- Once something’s selected, you can use Up/Down to shift a parameter, or Ctrl+Up/Down to transpose.
- The hand tool can be accessed by Ctrl+click, instead of being a separate tool.
- Seeking is by Shift+click. To reset the playhead after playback, stop the song (ESC) instead of pausing (space).
- Instead of a unit view, you can pin units above the piano roll. See info about the unit tab below.
- More gestures and shortcuts for navigation and editing, described below.

## What does X mean?

Voice tab

1. Repeat sample. For wav and ogg voices, you can toggle this to have the sample stop after one loop, or repeat as long as the note is held.
2. Beat fit. For wav and ogg voices, you can toggle this so that on A4, the sample always plays for 1 whole beat. This is useful for certain percussion sounds if you want to fix their start and end times. For example, you wanted something to sound for 4 beats exactly, you could put it 2 octaves below A4.
3. Base key. If beat fit isn’t checked, change this to transpose this voice by a number of semitones. It’s inverted, so lower it if you want everything to sound higher. Double-click to edit.
4. Name. The name of the voice. Double-click to edit.

Unit tab

1. Visible. Toggle if the unit is visible in the background while you’re focused on a different unit.
2. Playing. Toggle if the unit is playing or muted.
3. Pinned. Toggle if the unit is pinned to the top of the piano roll, so that you can edit its note timings even while another unit is focused (useful for drums). Editing a pinned unit is similar to the regular piano roll - click to add notes, right-click to delete.
4. Name. The name of the unit. Double-click to edit. Ctrl+click to select it for copy / paste.

Effects

1. Group. Which unit group should this effect apply to?
2. Unit. Together with frequency, determines how often the echo should play. The name is a bit misleading since units already have a different meaning in pxtone. Options are Beat, Meas, Sec.
3. Frequency. How many times should the echo play within one “Unit”. For example, if set to 3Hz and Unit is Beat, it will play 3 times in a beat.
4. Ratio. How loud should an echo be compared to the previous one?

1. Group. Which unit group should this effect apply to?
2. Cut. What’s the amplitude ceiling in this group?
3. Amplification. How should the volume be scaled for units in this group?

Overdrive is a bit difficult to explain. It might be best to play around and hear what you like. Additionally there're more information here.
Miscellaneous

1. Users connected to this session. Each row shows a user’s ID, name, and ping.
2. Watch another user. You follow their cursor, window position, playhead, and current unit. You can input a note or watch yourself to stop following.
3. Local playback volume (doesn’t affect song).
4. Playback buffer length. If your audio is choppy, try raising this. It will add some audio latency though.
5. The parameter you’re currently editing.
6. Quantization for your current note (e.g., if Snap X is 1/3, you can place notes 1/3 of a beat long). Snap lets you do microtonal placements.
7. When copying and pasting, this determines if you want to include the current parameter in the copy. Note: velocity controls whether or not the notes themselves are copied.
8. Follow playhead. Toggle this to automatically scroll if the playhead falls offscreen.

## How do I...

Edit with friends?

To edit with friends, one person has to host a server. This can be a bit complicated depending on your network setup.

First, you have to tick "Host" in the New Session window.

If your home internet uses a router, though, you might have to set up port forwarding, so that computers outside of your network can connect to you. Many multiplayer game servers usually need something similar.

Copied below is a brief guide on how to do this, from here.

- Go to the router configuration site (Often 192.168.1.1 or 10.0.0.1; it depends on your router model, so you should probably find that out).
  - You might see a login screen that looks like this. Your router usually will have information about how to log in.
- Go to the "forwarding" or "virtual servers" page
- Create a new forwarding entry: port 15835 (or whatever port you want to host on), TCP protocol (or Both) and the local IP address of your computer.
  - There are guides online to help figure out your local IP address, for example here.
  - My own setup looks something like this.

If you have a local firewall (Windows firewall, Comodo, McAfee, F-secure, etc.), you need to configure that as well. For more detailed guides, check out portforward.com (you generally don't need to download anything).

Once the server is up, others can connect to it by going to File > Connect, and in the Connect dialog, type in your public IP (which you can find here), then a colon, then the port you're hosting on.

Navigate my project quickly?

This may mean one of two things: moving to different times in the song, or to different units.

Jumping around to different times in the song usually involves the mouse. In particular:

- Ctrl+scroll and Ctrl+shift+scroll to zoom in and out.
- Middle-click drag to pan around.

Here's a video.

Jumping around to different units can be done with either the mouse or keyboard. Options:

- You can click on the units in the unit tab.
- You can press W / S / PgUp / PgDn to go to the next / previous unit.
- You can press 1..9 to jump to that numbered unit.
- You can press R and click to jump to a pinned unit, or a unit in the background of the piano roll.

Here's a video.
Copy and paste?

Make a selection with Ctrl+Shift+Drag.

Press Ctrl + C and make a new selection somewhere else.

Press Ctrl + V.

#### Advanced copy and paste

You can also copy and paste over multiple units if you Ctrl+Click the unit names to select other units.

#### Video

The video below shows normal copy-paste, then a copy-paste with multiple units.

You can also copy and paste over multiple units if you Ctrl+Click the unit names to select other units.

Additionally, the “Copy” checkbox in the bottom left can be used to set only certain parameters to be copied. If you want to only copy panning, for example, you can untick the checkbox for each other parameter setting, then copy and paste.

Portamento / vibrato?

Set the portamento length in the parameter editor. Then draw a note somewhere afterwards.

Ctrl+click somewhere in the middle of the note. This changes the pitch of the note without creating a new note.

You can tell it’s the same note if the bullet in the measure ribbon isn’t broken into two, and there’s no highlight at the start of the second block, as in the picture on the left.

The note will slide smoothly from one pitch to the next over the portamento length you set earlier.

Update! Ehm has made a helpful video about how portamento works. It's for ptcollage, so the UI is slightly different, but the principles are the same. One difference is that Ctrl+click is how you use the finger tool in ptcollab, instead of pressing a specific button.

Use MIDI input?

Go to Options > Settings > MIDI and select your midi device.

From here, there are two ways to input midi: live or with step controls.

Press Ctrl+R to enable recording, then start the song and play your notes! If you're like me and not great at playing perfect rhythms, you might want to quantize your notes afterwards. The shortcuts list below describes how.

To record with step controls, input notes while the song isn't playing, and use J/L to move back and forward in time by the current quantization. Make sure you're still in recording mode.

Here are some useful shortcuts:

- Quantization: Select (see Copy and Paste section above), then Alt+Q.
- Change quantization length: I/K.
- Backspace: delete previous note (mainly useful for step controls).

Glossary of shortcuts

All the shortcuts are in the editor help, but here are some common ones:

- Space to play/pause, Escape to stop, Shift+click to seek
- Ctrl+Z and Ctrl+Y/Ctrl+Shift+Z to undo and redo
- Ctrl+click to modify just pitch values, not notes (useful for portamento)
- Selection
  - Ctrl+shift+click to select
  - Ctrl+A to select all
  - Ctrl+shift+rclick or Ctrl+D to deselect
- While something is selected:
  - (shift) up / down to transpose or shift parameters. Add Ctrl to shift by an octave.
  - Ctrl+C and Ctrl+V to copy/paste
- Keyboard shortcuts for navigation:
  - W/S for next previous / next unit (PgUp / PgDn also work)
  - Q/A for previous / next parameter
  - F1..F4 for the tabs in the menu
  - 1..9 for jumping to a unit directly
- Mouse-related shortcuts for view / mode changes
  - Middle-click drag to move around
  - Shift+wheel to scroll horizontally
  - Ctrl+(shift)+wheel to zoom vertically (horizontally)
  - Alt+wheel to change quantization