nesdev.com

Pently is a music engine for NES designed to combine musical flexibility with space efficiency.

Latest tagged version is 0.05wip11
Bleeding edge features in the GitHub repository

----

There's demand to package the music engine of Concentration Room, Thwaite, Zap Ruder, DABG, RHDE, and Sliding Blaster. But before I go wild adding a pointy-clicky ooey-GUI façade, I need to get what I have into releasable shape. This means I'll need to document it, make example files exercising all features, benchmark it, and announce it. For now, let me know if any of the draft manual is hard to understand.

Later releases may include a translator for an MML-like language, a player with piano roll display, and a tracker.

Here's some feedback on your draft manual.


Overview unclear

What language is this library for? What kind of file do Pently commands go into? How do you include the Pently stuff into an NES development project?

After I read the manual, I gather Pently is made of the following pieces, but I don't understand how they all fit together.

• methods
  sound effects table and its entries
  instruments table and its entries
  songs table and its entries
  conductor track and its commands
  patterns and their rows of commands

Maybe you could write an Overview section that describes how these pieces fit together, then have sections for each piece with more details.


Pitch codes

The first place you mention the pitch codes N_C and N_CH, I was confused what they were because they hadn't been explained yet:

Pitch values such that the pattern code N_C produces a C are [...] For example, [...] N_CH produces a middle C and N_C produces the C an octave below it.

Later you mentioned N_BB, and I wasn't sure what the BB represented:

For example, to play a short note for 4 frames followed by a note that is as long as a quarter note minus 4 frames, do GRACE,4,N_CH, N_BB|D_Q4.

You finally imply the pitch code meanings at the end:

The following are all the symbols that are valid in pattern bytecode:
Notes, low octave: N_C, N_CS, N_D, N_DS, N_E, N_F, N_FS, N_G, N_GS, N_A, N_AS, N_B
Notes, high octave: N_CH, N_CSH, N_DH, N_DSH, N_EH, N_FH, N_FSH, N_GH, N_GSH, N_AH, N_ASH, N_BH
Note, top of range: N_CHH
Notes, enharmonic synonyms: N_DB, N_EB, N_GB, N_AB, N_BB, N_DBH, N_EBH, N_GBH, N_ABH, N_BBH

Maybe the pitch codes should be briefly explained somewhere, and any early references should mention or link to where they're explained later.

For example, you might briefly explain how the pitch codes work (maybe insert those four lists of note codes) after this point:

Each note is specified as a pitch relative to the transposition base. Only one note can be played on a channel at once. To stop a note without playing another, use a REST.

Fine meaning

fine [...] This command stops music playback.

In sheet music, the Fine notation means you stop the second time you encounter it. I'm confused if Pently's fine means "stop unconditionally" or "stop the second time".


Noise values

Pitch on a noise channel is $03 (highest) to $0F (lowest) for ordinary noise

I thought there were 16 possible noise values. Are you excluding some on purpose?


Why < and - ?

TRANSPOSE,<-12 moves down an octave

Why do you need both a < and a - here?


Missing symbols

Many of the symbols show up as boxes in my browser (Internet Explorer 11 on Windows 8.1). I can see the sharp and flat symbols, but not the "final barline", segno, and note symbols.

Thank you for the feedback. I have updated the manual to address some of the issues you brought up.

What language is this library for?

It's written in assembly language but should work with any language that runs on the NES and can link to assembly language subroutines. I've added the names of the essential files.

Maybe you could write an Overview section that describes how these pieces fit together

Good idea. I've slipped "The file musicseq.s contains the sound effects, instruments, songs, and patterns that you define." into the API section.

The first place you mention the pitch codes N_C and N_CH, I was confused what they were because they hadn't been explained yet: "Pitch values such that the pattern code N_C produces a C are"

That's a forward reference. Do I always need to use the word "below" on every forward reference?

Later you mentioned N_BB, and I wasn't sure what the BB represented: "For example, to play a short note for 4 frames followed by a note that is as long as a quarter note minus 4 frames, do GRACE,4,N_CH, N_BB|D_Q4."

Another forward reference. Will change to "For example, to play a short C note for 4 frames followed by a B flat that is as long as a quarter note minus 4 frames, do"

You finally imply the pitch code meanings at the end:

I'll explain them explicitly with a table at the start of the "Patterns" section.

In sheet music, the Fine notation means you stop the second time you encounter it. I'm confused if Pently's fine means "stop unconditionally" or "stop the second time".

I changed the explanation to lead with what it means: "Stops music playback. Use this at the end of a piece." To make an A-B-A form, you'd repeat the play and wait commands for A and then add a fine command. But in video game music, if you have an A-B-A form, it's usually one that you'll be looping.

"Pitch on a noise channel is $03 (highest) to $0F (lowest) for ordinary noise"

I thought there were 16 possible noise values. Are you excluding some on purpose?

I added the explanation: "Values $00 through $02 are also valid, but they sound identical to quieter versions of $03."

Why < and - ?

"TRANSPOSE,<-12 moves down an octave"

The - denotes negative, and the < works around ca65's lack of support for signed bytes.

Many of the symbols show up as boxes in my browser (Internet Explorer 11 on Windows 8.1). I can see the sharp and flat symbols, but not the "final barline", segno, and note symbols.

Many systems ship with fonts with glyphs for the flat and sharp symbols; fewer support the Musical Symbols block. On my Xubuntu laptop, Pango is pulling those symbols out of the "FreeSerif" font by default, and Character Map says they're also available in "Symbola". And those are pretty much the only real fonts that support them according to Font Support for Unicode Block 'Musical Symbols' on FileFormat.Info. (LastResort doesn't count because it's an OS X internal font that has the same glyph for all characters of each Unicode block.) See also Test for Unicode support in Web browsers: Musical Symbols (U+1D100 – U+1D1FF) by Alan Wood.

On GNU/Linux distributions descended from Debian, the administrator can install the Symbola font using sudo apt-get install ttf-ancient-fonts. As for proprietary operating systems, I'm surprised that they fail to include Musical Symbols fonts despite racing to support new emoji characters in each Unicode version.

With no further feedback for nearly a week, I think I have something you can bang on. Let me know if you can get it to do anything.

I see you're using ca65. I don't see a .cfg file. Can ld65 run without a .cfg?

Honestly, without a GUI/Tracker, I don't know if I would be able to do much with it. I do like some of the features. But, at current, the learning curve might be too high for most users (or maybe it's just me).

No pitch bends or vibrato.

This might be a deal breaker for me.

dougeff wrote:I see you're using ca65. I don't see a .cfg file.

The NES shell is currently using a Zap Ruder-era (fourth quarter 2011) version of my project template, where I hadn't yet renamed the linker configuration file from nes.ini to nrom128.cfg.

Honestly, without a GUI/Tracker, I don't know if I would be able to do much with it. I do like some of the features. But, at current, the learning curve might be too high for most users (or maybe it's just me).

Would the learning curve likewise be too steep (X=proficiency, Y=time) for MML or LilyPond? RampantWonder asks the same question.

No pitch bends or vibrato.

This might be a deal breaker for me.

True, it currently operates on a "fretted" pitch model, where all pitches are quantized to semitones. But it has the equivalent of FamiTracker's arpeggio envelopes, used to create the bass instrument in "stairs". It also has "legato" and "grace note" effects, which can be used for appoggiatura (pitch change at the beginning of a note) such as in "Happy Flappy Crappy".

It's obvious you put a lot of work into this. I will try to use it sometime this week.

learning curve

Imagine you are new to nesdev, and you just wrote a game, now how do I add music? Famitracker to Famitone2 would be easier. So, they would do that...and get used to it, and probably keep using it. Maybe yours is TONS better than Famitone2, but without an easy to use interface (Famitracker), people may not use it.

If you made a famitracker-text-export to Pently conversion tool, it might help.

Edit: oh, I see you are going to write a tracker...

Later releases may include a translator for an MML-like language, a player with piano roll display, and a tracker

Imagine you are new to nesdev, and you just wrote a game, now how do I add music?

First you have to find someone to compose original music because the royalties for licensing an existing song for use of a cover version in a game would likely exceed what a hobbyist can afford.

If you made a famitracker-text-export to Pently conversion tool, it might help.

Say you want to base the Pently authoring model on conversion from FamiTracker. I can see three ways this might play out:

1. How would you key into FamiTracker a composition using a feature supported by Pently but not FamiTracker? We recently had a topic about such features.
2. Or is it worth it just to make an exporter that handles those features supported by both Pently and FamiTracker and have composers ignore those features supported by Pently but not FamiTracker, treating Pently as essentially an alternative to FamiTone?
3. Or did you mean create the basic outline of the composition in FamiTracker, export it from FamiTracker, convert it to a file in Pently's MML-like language, edit the result of conversion to drop FamiTracker-only features and add Pently-only features, and then make all further changes in this file rather than in FamiTracker?

If your answer is "any of the above; it's up to you", what are the pros and cons of each? If it sounds like I'm asking a lot of questions, it's because I want to make something that people are actually likely to use.

Edit: oh, I see you are going to write a tracker...

This will take time. Before I get around to making my own tracker, I'll need to define the tracker's native format. I plan on making it a textual format somewhat like MML or LilyPond for two reasons: to bring on board composers familiar with those environments before I finish the tracker, as well as to allow files to be usefully checked into version control with diff support.

Re: Famitracker to Pently.
Just getting the notes to convert to Pently syntax would be helpful. But, if you are making a tracker, this might be unnecessary. As long as there is some quick/easy way to input music.

I've never used MML or LilyPond, so I'm not familiar.

Apparently, musescore can import/export MIDI and to Lilypond format, and others.

I don't know if that's helpful, but supporting Lilypond syntax might make sense.

It seems to me that support for both tracker and MML would be a good thing to have. MML does not seem to me to be a very good format for the native document format of a music tracker (Csound numeric score seems a better format for this purpose, which can even add support to the tracker for some advanced stuff; I have also written a program to compile MML into Csound numeric score format), but with comments to annotate it could be done (another alternative would be for the GUI to use annotated assembly language as its document format).

However, neither of these seem suitable for the way Pently is working using conductor track. A GUI could easily represent it though, by having the patterns and other conductor commands placed into a grid. For text format, a variant kind of MML can be done. You can have "Full MML" which supports ABCDEZ tracks, and "Conductor MML" which is a subset of Full MML that supports only the Z track; a compiler can optimize and convert Full MML into Conductor MML, which is then compiled into assembly language.

Patterns can be defined by lines starting by stuff like !1 and so on (you could do something like !1,2,3 to add the same notes to multiple patterns simultaneously, somewhat like ABC in common MML); the MML compiler then automatically determines the length and base transpose value for each pattern (and base instrument if the pattern begins with an instrument selection), and then in the Z track you might specify (A1B3) to play pattern 1 on the first square wave channel and pattern 3 on the second square wave channel, and then emit a waitRows command (looping or not looping patterns that are too short based on notations in the pattern itself). You could use !A1 to begin a pattern in ostinato mode (not emitting waitRows at this time) and then perhaps !A. to stop ostinato mode. Loops in the Z track can automatically be compressed as necessary (example could be something like [(A1B2C5)(A1B3C5)(A1B4C6)]4).

These are just some idea about it; there can be more possibilities too.

So I'm looking through the code for how it handles NTSC/PAL speed and pitch (fortunately it looks trivial to hack in my conception of how the tvSystem var should be). Am I correct to say that the pitch compensation is handled by just playing 1 semitone higher? If so, I guess a 28 cent difference isn't too bad of a trade off for omitting another 160 or 128 byte table.

43110 wrote:So I'm looking through the code for how it handles NTSC/PAL speed and pitch (fortunately it looks trivial to hack in my conception of how the tvSystem var should be).

0: NTSC or RGB; 1: PAL NES; 2: Dendy

Am I correct to say that the pitch compensation is handled by just playing 1 semitone higher? If so, I guess a 28 cent difference isn't too bad of a trade off for omitting another 160 or 128 byte table.

Yes. And the pitch is even closer between PAL NES and Dendy: about 12 cents higher on Dendy.

Right now I'm trying to figure out how to implement alpha-to-gray in SDL 2 so I can get rolling on building a GUI framework for the tracker. Reply if you have experience with SDL 2. Or I could try learning GTK+ or Qt instead? If GTK+ or Qt, is there a good way to abstract over audio in Linux, Windows, and OS X?

tepples wrote:If GTK+ or Qt, is there a good way to abstract over audio in Linux, Windows, and OS X?

Qt does come with QAudioOutput built in, although I remember having some trouble with it (can't remember exactly what, but it was something fairly minor). Not sure how good it would be for a latency-sensitive application.

The two popular textual music description languages that I'm aware of (MML and LilyPond) express durations (half note, quarter note, eighth note) of successive notes differently. In MML, setting a duration on a note affects only that note: l8 c d e4 f g makes the E a quarter note but all the rest eighth notes. In LilyPond, on the other hand, setting a duration affects all later notes: c8 d e4 f g makes the C and D eighth notes and the rest quarter notes. I'm supporting both behaviors in Pently's music compiler tool, selected with the command durations temporary or durations stick. But I wonder which to make the default.