Sounds like you may have just about earned your weekend! 
Have a good one.
On Sunday I hope to return to the media server and try out the latest update.
1 Like
Thanks @Derek.
Re the media server, would you mind checking that after updating to the new version your existing setup works as before. It should but if not let me know what broke and I’ll try to streamline it.
1 Like
Thrilling to see this being added Brad! One tip (from experience): if you’re trying to implement some logic, you might be starting to get into problems fast. Also get a lot of questions (but what if I want this logic, or combined, or …).
In a few projects I have been using Liquid. It’s supported for .NET with Fluid.Core, but there are also LiquidJS. It’s high performant parsing of text combined with data you provide. Could be an option too if you are looking for a way to add logic. Just a suggestion. 
Thanks
Not sure I follow? What sort of logic problems?
None of this is .NET - all Javascript
Not really sure how I’d use this in this project. Looks similar to a templating engine (moe-js)I once wrote.
Whitespace Directive (line wrapping control)
The !white-space directive let’s you control line wrapping:
eg: white-space normal
vs: white-space pre-line (pre-line = “pre-formatted lines”)
3 Likes
Push/Pop Directives (save/restore styling state)
The !push and !pop directives let you save and restore the current display style:
eg:
1 Like
Message Directives
In the push/pop video above you might have noticed the little error boxes when you have unbalanced push/pop directives. I’ve also made a set of these message boxes available as utility directives for showing errors, warnings, etc…
1 Like
Loving all this functionality.
I’m curious. When you pop, do all the styles get cleared or does it just set properties to previous values? Looking at your example where the middle section has the bg colour set but the style being restored doesn’t set the bg colour.
That kind of embedding of the browser window into Cantabile is exactly what I was looking for - the controller bar is visible, the metronome bar is visible, but there is enhanced capability on the notes screen. One feature I use frequently is switching from seeing notes to seeing the setlist grid during performance via hot key, so perhaps add that to your “Later” list. Re getting separate notes to bandmembers, if media server remains a separate tool it is quite easy to do that and I already tried it with my band (I use one channel for videos, one for lyrics, one for messages).
It restores the styles to how they were when the !push was done.
At the point of the !push the background color wasn’t set. When the pop happens, the background is restored to unset.
Yep. This is still a way off, but definite possibility.
If just did a quick test with this - the set list grid definitely can appear “over” the web browser in the background so swapping between the two views works fine. The only problem right now that I’ll need to fix is the short cut keys get intercepted by the browser. ie: at the moment, pressing Ctrl+G shows the browser’s find box instead of switching to the set list but I’m sure (hopefully) there’s a way around this.
Yes, but at the moment, you’re limited to PDF files. The idea is this would deliver these formatted and state controlled notes to different viewers.
Brad
Quick update… nothing to show!
I’m currently investigating Markdown processor alternatives and considering writing one so I can properly integrate these show notes directives.
Phew! I just came dangerously close to writing a markdown parser. I’ll take that route if I need to, but this might work…
I really wanted to get this directives much more tightly integrated with the Markdown processor because it removes a lot of weird behaviour.
After looking at a number of existing Markdown engines I think I’m going to switch to commonmark.js. Although it’s not directly extensible, its code base is reasonable easy to follow so I’ve created a fork of the project and will modify it to do what I need.
What’s the difference?
- In all the examples above, the directives were preprocessed and everything between them was treated as separate markdown documents. This produces some unexpected behaviour because the pre-processing has no concept of what’s going on in the surrounding markdown.
- With this new approach, the processing of directives is tightly integrated with the rest of the markdown processing - it behaves much more predictably and provides a lot more context information for the directive processing.
The only downside: Commonmark doesn’t have all the formatting features of some other libraries. Most notably it doesn’t support tables, but I can live with that at least for now.
See below for some screen shots of my modified version showing some basic style directives working.
Note:
- directives look the same as before but they also work much more sensibly in blockquotes (ie: they can be used after lines starting with !)
- Styles get restored automatically after leaving nested blocks
- directives are correctly ignored inside code blocks
- The first screenshot shows the final result
- The second screenshot shows the html
- The third screenshot shows the Abstract Syntax Tree of the parsed document - note how the directives are fully integrated into the document tree.
Next job is to move all the existing directives from the old system to this new approach.
Screen Shots
1 Like
Well, I think this decides it. I was worried about getting !if / !else / !elseif / !endif directives working with this approach because unlike most of the other directives they’re a multi-line construct.
It took some experimentation, but I think I’ve got it working so that a construct like this:
!if state == "A"
!if view == "primary"
Primary
!endif
State A
!elseif state == "B"
State B
!else
State C
!endif
Produces an abstract syntax tree like this:
<document xmlns="http://commonmark.org/xml/1.0">
<conditional>
<conditional_branch expression="state == "A"">
<conditional>
<conditional_branch expression="view == "primary"">
<paragraph>
<text>Primary</text>
</paragraph>
</conditional_branch>
</conditional>
<paragraph>
<text>State A</text>
</paragraph>
</conditional_branch>
<conditional_branch expression="state == "B"">
<paragraph>
<text>State B</text>
</paragraph>
</conditional_branch>
<conditional_branch expression="">
<paragraph>
<text>State C</text>
</paragraph>
</conditional_branch>
</conditional>
</document>
That’s everything required for the HTML rendering side of things to produce the required scripting code to update these elements in realtime.
Nice! I’m feeling optimistic about this…
2 Likes
If you’re not technically minded, you might be wondering what I’m going on about with all this, but I’m including it for those who are interested and because writing it down helps me clarify my own thinking about it (and might be handy to refer back to later)
There’s lots of moving parts here but much of this is much lower level that you’ll ever have to deal with - there is a bigger picture I’m thinking about and it should all come together eventually.
Also, at this experimentation/proof of concept stage it’s pretty typical for there to be false starts, rethinking and changes of direction.
Bear with me!
7 Likes
I’ve been following this fascinating dev log on Show Notes 2, and I’m really excited to see some moves to reinvent the Show Notes feature in Cantabile. It’s something I use heavily, and have come to both love it, and find some of its limitations frustrating. So I’m really keen to see what can be done!
I really like the idea of storing show notes as plain text, rather than embedded in song JSON files. This will make it easier to import/export with other formats, and it’ll be especially nice for those of us who store their Cantabile song data in a version control system!
Stepping back, I was wondering what the use cases are for conditional logic in the show notes, besides switching for different song states. Are there many situations where that level of conditional control would be necessary? It does seem to bring with it some complications, both in terms of engineering and for the end user. It does sound very powerful, but at the same time, perhaps unwieldy for users who might not feel comfortable dabbling in conditional logic for switching pages of notes.
I also wonder if it could be frustrating if you rename/reorder states in the song, having to make sure the conditional logic in the show notes file is kept consistent.
For a while now, I’ve wondered about a new approach to Show Notes (before these recent new developments), whereby a song would have a simple master/template file that outlined the basic formatting for show notes pages for the song, as markdown, but no state-dependent content. So it could include font stuff, colours, but also any heading or footer info, or anything else that’s not state-dependent (though it could include variables that might change in value, such as state name).
Each actual state-dependent page would have its own separate show notes markdown file, containing the actual notes. They could also include formatting-type stuff, but that would be local to just that page.
The master/template file would also include a directive that Cantabile replaces with the markdown corresponding to the current state in the required place, from the appropriate file. Or as a more flexible alternative, directives that map state names to show notes files, to give you the ability for single pages to be shown for multiple states (e.g. repeating the chorus multiple times). And potentially for multiple blocks of markdown to be inserted in different places within that template file. Or perhaps that mapping information remains in the Cantabile song file. A variation on this for rendering PDFs might be that the PDF file is specified in the template/master file, and directives indicate which page to render for each song state.
It would remove the need for conditional logic for state management, yet still provide the ability to have different notes for different states. It would provide a way to “theme” in a consistent way, so all the notes for a song would follow the same formatting/layout. It would also make it easy to share that consistent layout across other songs without having to strip bits out potentially mixed in with the note content.
Current state control in Cantabile allows for blocks to have state-dependence (or not) for text, image, colours and visibility. Another way of saying this is that regions should either have the same content for the whole song, or different for each state. The stuff that remains the same for the whole song could appear in that master/template file, and song-dependent stuff in the various “content” files.
Granted, it might not be quite as flexible as using conditional logic, but might be a whole lot easier to implement and use, for the majority of real use cases. And there’s no reason why conditional logic could be added on top, for any further use cases requiring it.
The master/template file, and the individual pages, could be kept together in a folder named similarly to the song, along with any other resources such as images/PDFs. Potentially when a song has “stabilised” and no longer needs any further tweaks, it could be managed as a zip file, for easier file management.
Just some ideas I had quite a while ago now, for how things might be done. Hopefully with some useful food for thought.
Neil
1 Like
I’d also like to suggest another feature for Show Notes 2 if I may.
With the current Show Notes system, I have a block at the bottom of each show note page that includes the first part of the next show notes page, so that I have a prompt/preview for what I’ll need to play immediately after I hit my “Next state” pedal.
This is a bit cumbersome to manage currently, as I have to copy a few bits from the next show notes page into the bottom part of the previous page. It also gets messed up if I find I need to insert a new state somewhere, or delete a state.
It would be great if there could be a way to optionally insert the top part of the note corresponding to the next state somewhere, as a look-ahead/preview. Perhaps it could just render the whole next page, but have a height constraint, so you only see the first n lines/pixels.
Neil
1 Like
Hi Neil,
Thanks for the excellent feedback.
Regarding conditional logic… I agree that for most users setting up new notes in the new system it’s probably overkill. But, I need a way to convert old shows to new and the conditional logic seems the easiest way to do that.
Regarding master/template… that’s an interesting idea. I had planned for the ability to !include other files and also the ability to !define macro blocks that can repeat content, but you’re right… a way to templatize blocks with content from elsewhere would be nice.
First thought on this:
- Directives
!sectionand!endsectionto mark out sections in a file. !templatedirective to say to wrap this file in an outer template file!include-sectionthat can be used in a template file to bring in content from file that references the template.
Regarding previewing the next song… another interesting idea. Maybe the ability to include sections from arbitrary files and mark out the first part of the next file as “preview” section.
Definitely food for thought! Thanks.
2 Likes
I was thinking more from a top-down standpoint, so a song would always reference a single master/template file, and that would then (potentially) reference other “content” files for state-dependence.
What I had in mind was something along the lines of this for a template:
!! Map song states to markdown files.
!map "Intro" "Intro.md"
!map "Verse 1" "Verse1.md"
!map "Verse 2" "Verse2.md"
!! Some general stuff applied across all states
!color lime
!font-size 18pt
Current part: $(State)
!! Layout of actual blocks
!insert-section "Main note" $(State)
!reset
---
!color grey
Next: $(NextState)
!preview-section "Main note" $(NextState)
And then the “content” files might look like:
!! Verse1.md
!section "Main note"
!preview-start
Piano:
Dm7 G7 CMaj7
!preview-end
Fmaj7 Em7
Dm7 G ... etc
!end-section
I just threw this together more for illustration than precision, but hopefully, it gives a picture of the kind of top-down way I thought it could hold together.
For simpler notes where there’s only one state-dependent section, you could also just drop the section stuff completely, and do !insert $(State), which inserts the whole content file (which would not need !section directives).
You could have a different master/template file for different “views”, for display on computer monitor, tablet, phone etc.
I’m not quite understanding why a file would need to reference an outer template - it seems like more dependency than necessary, unless I’m missing something.
Neil
Quick update…
You could be forgiven for thinking I’d given up on this, but I’ve been working flat out on this. Well, not directly, but I’ve been busy on a front-end web framework side project that I started some months ago that I really want to use in this show notes work.
Anyway, I’m back on show notes proper now and expect some new updates on this soon (hopefully).
5 Likes