Pently: a flexible, space-efficient NES music player

[tepples]

Before working on the arpeggio enhancements, I wanted to get some changes out into a tagged release for those who don't follow me on GitHub.

0.05wip6 (2017-06)

• Patterns can change channel volume in 25% steps
• Rest in attack track no longer corrupts pulse 1 arpeggio
• pentlyconfig.inc: Change engine's code and data segment; disable pulse channel effect pooling and volume comparison; change initial $4011 value
• Optionally enable sound effects in NSF
• pentlyas.py: Improved diagnostics emitted by play command. Shows song name; emits one for playing pattern too low.
• pentlyas.py: Command line option to change output segment
• pentlyas.py: Clamp vibrato depth to in-range values
• pentlyas.py: Ignore loops in volume envelopes, presumably pasted from FamiTracker
• NSF header gets load address from linker configuration
• Document use of equal temperament
• Add "Sticks" sample song

[tepples]

Pently 0.05wip7 has three key improvements: portamento, slow arpeggio, and richer ways to express arpeggio.

• Change to zlib license, which preserves the spirit of the original license but is recognizable by GitHub
• Add portamento, the single most requested feature
• paldetect: Interleave with vwait so as not to depend on NMI handler
• pentlyas.py: Add 8 predefined chord names (M, maj7, dom7, aug, m, m7, dim, dim7)
• pentlyas.py: Score can define new chord names
• pentlyas.py: Add single-note arpeggio syntax similar to LilyPond chord mode (thanks to retrodpc for testing)
• pentlyas.py: Option to name chord by its top note instead of bottom
• pentlyas.py: First and second inversions of chords
• Arpeggio can be set to slow or fast (requested by w7n)
• Add "Arpeggio Waltz" song demonstrating new features
• Document that object names follow identifier rules
• makefile: Launch Python tools with py.exe on Windows

[tepples]

Pently 0.05wip8 is expected to be the final release of this calendar year.

• Reduce BSS (main RAM) footprint when several effects are off
• Reduce ZP footprint when attack phase is off
• Compress 0-pitch frames of instrument envelopes
• pentlyas.py: correctly parse drum names starting with "l"
• pentlyas.py: option to change overall tuning up or down from A440
• pentlyas.py: special filename - means standard output
• pentlyas.py: output lists each song's total size in comments
• Add "Isometry" song demonstrating attack track more thoroughly
• makefile: change score filename
• NES shell: move copyright notice to status bar
• NES shell: status shows ROM size and current and peak CPU usage
• NES/NSF executables no longer in Git; will be in releases instead

Is anyone actually using this?

[FrankenGraphics]

Personally, i mean to get into pently and try it out once i have one or two balls less to juggle, because it looks very promising. Separate attack portions make a lot of sense. Were you planning on a dedicated tracker?

[tepples]

I even prototyped effect symbols for a new tracker, but I too have many balls to juggle.

[tepples]

Based on discussion about conveniences for MML composers a few days ago, I've been adding enhancements to playback in Pently's NES shell (see bug 27).

• Visualizer: See what notes are playing on the main pitched tracks and what pitch and volume are output on each channel
• Rehearsal marks: Navigate to sections of a song
• Track muting: Disable or enable note-ons on a track. This works on tracks, not channels, letting you (for instance) hear a channel's own track separately from drum and attack track overlays that play over it. I've even added the same double-click behavior as FamiTracker: solo if any other channel is unmuted; otherwise unmute all.
• Resume point: When the ROM starts, jump to a specific row of a song with specific channels muted.

So here's an interim player release built from the head of my tree. Try it and see if my navigation, visualizer, and track muting are in any way helpful. Press A or B to switch between the song list and the visualizer. On the visualizer, use up and down to jump to a section or left and right to move to the mute controls.

[tepples]

Pently 0.05wip9 is out

This release adds several features useful for iterating on part of a piece, such as a visualizer, channel muting, seeking to rehearsal marks, and slow motion playback. It also adds an editor to create sound effects right on your console.

Engine changes

• PENTLY_USE options to disable music engine entirely, disable 303 portamento, and enable triangle channel duty fix
• Regression fix: Cancel injection when attack ends (had been broken since slow arps)
• Cancel grace note when pattern begins
• Add rehearsal transport control to skip to a row or slow down or pause playback
• Add variable mix to mute tracks
• Store current pitch and volume for use by visualizer

pentlyas.py changes

• Add warning infrastructure
• v1 through v4 as synonyms for pp through ff
• p (pause) is synonym for r (rest)
• q repeats last chord, as in LilyPond
• Bar check in pattern to warn if not on a measure boundary
• pickup works in patterns as well
• Unreachable A in tunings below A=437 is nonfatal
• mmloctaves off, which future chord syntax will require
• Set rehearsal marks for navigation in score
• Set initial playback position and track muting

NES shell changes

• Add per-song screen with visualizer, rehearsal mark navigation, track muting, tempo, and pause-and-step
• Import Sound Effects Editor as of 2014-09-10

Manual and other changes

• Script to estimate pitch of 93-step noise
• docs: Recalculate PENTLY_USE savings

[zzo38]

One suggestion of thing to add could be the octave mode that < and > makes the octave permanent while ' and , makes the octave temporary (a few MML compilers support this).

Also, I do not see any description of the mmloctaves command in the documentation.

[tepples]

One suggestion of thing to add could be the octave mode that < and > makes the octave permanent while ' and , makes the octave temporary (a few MML compilers support this).

Which compilers, so I can plunder their manuals the way I did the ppMCK guide? Do they allow one of < or > and one of , or ' on the same note?

Also, I do not see any description of the mmloctaves command in the documentation.

[/quote]
That's because the feature controlled by mmloctaves is not yet implemented. I reserved that keyword a release in advance, intending to use it for LilyPond-style chorded notation for arpeggios, where <a c e>4 means the same as the chordmode-inspired a4:37.

[zzo38]

One suggestion of thing to add could be the octave mode that < and > makes the octave permanent while ' and , makes the octave temporary (a few MML compilers support this).

Which compilers, so I can plunder their manuals the way I did the ppMCK guide? Do they allow one of < or > and one of , or ' on the same note?

The only ones I know are AmigaMML and my own improved version of ppMCK (there may be others, but I do not know of any), and yes they do allow both on the same note. (Actually, it doesn't use , for this purpose, but if implementing it in Pently, , is already used to specify octave so it might as well to still do.)

Here is a copy of the relevant parts of the AmigaMML documentation that have to do with octaves (so that you need not download it if you do not want to):

c d e f g a b = Play notes by letters. You can include + (sharp) - (flat) ' (high octave) _ (low octave) after each note, to change them by one or twelve semitones each; using multiple symbols (even multiple same ones, such as double-sharp) is possible. After that, you can include a number to override the note length, and then you can include dots to increase the note length.

o = Set octave. For Amiga mode, range is 0 to 4 (default is 2), although the actual Amiga limit is octave 1 to 3 and some programs might not work with numbers outside of such limit. For Extended mode, the range is 0 to 7 (default is 4).

< > = Make low octave/high octave.

(The o command here is one that all MML compilers I have seen implement (although the description above is for Amiga; the range may differ for NES/Famicom). Pently does not seem to have this, but it probably should be added, which then sets what is considered as "previous note" without actually adding a note. AmigaMML uses _ as the low octave suffix, but Pently uses , instead, which should still be OK; Pently is already difference from MML anyways, so it need not be the same way exactly. Also, maybe this documentation is unclear, but I wrote AmigaMML, so I know that <> is permanent while ' is temporary.)

Also, I do not see any description of the mmloctaves command in the documentation.

That's because the feature controlled by mmloctaves is not yet implemented. I reserved that keyword a release in advance, intending to use it for LilyPond-style chorded notation for arpeggios, where <a c e>4 means the same as the chordmode-inspired a4:37.

Ah, OK.

[tepples]

The only ones I know are AmigaMML and my own improved version of ppMCK (there may be others, but I do not know of any), and yes they do allow both on the same note. (Actually, it doesn't use , for this purpose, but if implementing it in Pently, , is already used to specify octave so it might as well to still do.)

Yeah, I was just curious if anyone else would use that feature of combining sticky and non-sticky octave changes. Thanks for quoting the manual. I may include it in a new "semirelative" mode.

o = Set octave. For Amiga mode, range is 0 to 4 (default is 2), although the actual Amiga limit is octave 1 to 3 and some programs might not work with numbers outside of such limit. For Extended mode, the range is 0 to 7 (default is 4).

I am accepting this feature request, with octave numbers interpreted the same way as in NerdTracker II and FamiTracker: o1 means C-1 through B-1, o2 means C-2 through B-2, etc., where NT2 and FT consider middle C to be C-3. Thus o1 would reset the pitch context as if the previous note were F-1, o2 as F-2, o3 as F-3, etc.

EDIT: Added in commit e9d89e0.

I reserved that keyword [mmloctaves] a release in advance, intending to use it for LilyPond-style chorded notation for arpeggios, where <a c e>4 means the same as the chordmode-inspired a4:37.

Ah, OK.

If you're curious, the relevant issue is Create arpeggios from chorded notes (#11).

[tepples]

There is a bug affecting triangle instruments and sound effects with non-final zero values. The fix requires adding 4 bytes of branch over the check for period high mismatch on non-pulse. It has been committed to the repository on MS GitHub and will be included in the next release.

[tepples]

Pently originally grew by adding features slowly over time. And some of them weren't necessarily added in straight-through order, resulting in a few parts whose control flow is a bit spaghetti. I recently completed a code review to produce English pseudocode, which led to a reorganization of parts of the instrument code. In particular, the processing for the sustain phase was moved above the pitch effects arpeggio, vibrato, and portamento, reducing the spaghetti factor and allowing more of what I call "inline tail calls" (a euphemism for fall-throughs). I plan a final release of Pently 5 by the end of this month.

But now I feel like I can no longer seem to keep up with demand for features.

1. One prospective user decides against it because there's no easy to understand authoring solution that a team of randomly hired chiptune composers can use to collaborate without what amounts to learning a programming language. So I made an MML-inspired score format and have my cousin make a converter from FamiTracker text export. There are things FamiTracker can do that Pently cannot and vice versa.
2. But that's still not good enough, as another prospective user wants vibrato, volume column, and portamento. So I added those.
3. But that's still not enough, as now the prospective user wants DPCM so bad he dropped Pently without even telling me.

Let's say I do add DPCM. Will that be enough? Or will developers soon demand support for Famicom expansion audio because they plan to bundle a jumper board for the NES-001 bottom expansion port with every copy of the game?

In order to design a representation of DPCM in Pently that is both space-efficient and musically practical, I have a few questions of people developing NES games that use DPCM in the music:
How many samples are in the soundtrack of your game? More than 25? More than 63? More than 127? And how much space do they total? More than 8K? How many of them are played at different frequencies, vs. played at only one frequency?

[dougeff]

I think DPCM would be enough to make people use it. Yes.

[tepples]

DPCM support alone is not enough if the DPCM support does not meet the needs of prospective users. Pently supported pulse 1, pulse 2, triangle, and noise since the first version, but people didn't want to use it because its support for pulse 1, pulse 2, triangle, and noise did not meet needs. This is why I ask what people want in the data model for DPCM, as a byte-for-byte replica of FamiTracker's DPCM instrument model would be space inefficient for a game, but something too limited would be seen as insufficient.