[sciurius]

Recently our band banned all books and went all-tablet. I will not deny that I played a part in that process . Our rehearsal breaks now look pretty much like a computer club...

A question that frequently pops up is: hows can I combine (fragments of) a score with a ChordPro lead sheet. The answer is no, you cannot. So I started thinking.

Basically, the generic is how to embed an image in a ChordPro. And I think this wouldn't even be that hard to implement.
So I propose a new ChordPro directive.

Code:

{image: uri width=nnn height=nnn border=0 center scale=nnn}

This is not unlike the <img> in HTML. The uri is mandatory, the other items are optional.
The choice for uri is to avoid platform issues with file names, however the most simple form (a plain file name without path) should also be allowed.
Width and height can be used to specify the desired dimensions of the image. The image will be resized if necessary.
By default the image will be stretched to the width of the display, this can be disabled with scale=0. Other values for scale will do what can be expected.

For example, a hypothetical ChordPro fragment and its hypothetical output.

Code:

[C]What you're gonna find who you want to be
But you [Bb]might have to pick between these three
{image: riedel.png}
{c:A capella + gitaarslagje/pingel}
[Dm]Rock Paper [Bb]Scissors which one [F]is it's your de[C]cision

   

The possibilities are numerous...

There are some open ends to this proposal (how to handle backup/restore, to name one) but I'm sure these can be worked out.

What do you think?

[itsme]

The layout options of ChordPro are a bit limited compared with an office program like LibreOffice. Nevertheless I use ChordPro whenever possible to use the option to transpose. Transposing does not make sense anymore as soon as I include sheet music fragments. Other images e.g. for decorating a song book are not important for me.
To combine sheet music with lyrics and chords I prefer including text sections into MuseScore .MSCZ files or exported sheet music images into LibreOffice / WinWord .doc / .docx / .odt files  and export as PDF.
For the combination of MuseScore and LibreOffice these tools looks promising:
MuseScore Example Manager http://extensions.libreoffice.org/extens...le-manager
or
LibreOfficeSongbookArchitect http://struckkai.blogspot.de/2015/04/lib...itect.html
Until now I have not tested any of these two, but I probably will give it a try as soon as my time allows it.

[sciurius]

Yes, there are other ways to combine images, lyrics and chords into PDF and import these files into MSPro, although you'll have a hard time to recreate the basic but nice formatting that MSPro does.
My proposal is specifically meant for images (of whatever kind) in ChordPro. And the images are in no way limited to sheet music, defeating the transpose feature. Even then, with the new ChordPro editor it is trivial to make small text/chord changes that would otherwise require a round trip via a PC running Word or LibreOffice.

[Zubersoft]

This is a very interesting idea. I don't think it would be too difficult to implement the rendering of the image (although I may have questions about all of the supported values/ranges for each proposed parameter), but I'm definitely not thrilled about needing to back up the files linked through that command. Those files wouldn't exist in the library anywhere, so it would require that in order for me to back up any chord pro file, I would first have to parse out any image commands used inside of it, figure out where the files are that are pointed to by that command (and I typically only support local files, and a uri would suggest that I should also support other targets such as a web address), and write those files into the backup file (which messes up the way backup files are currently processed). If the uri points to a valid path on one tablet, but not another, then I have to think about either just not restoring the file, or assigning a different path to it and having to dynamically modify the chord pro file to point to a valid path. All of these things can probably be handled, but I would only want to do it if it provides a very useful capability that a lot of users would benefit from. Just supporting the command itself isn't a big deal though - it's just the backup/restore that concerns me.

Mike

[sciurius]

That's what I expected... And that's why I went for a uri to designate the image source. When the uri points to an image somewhere on the web, it cannot be backup up and restored anyway.
So, in short, it is the users responsibility to make sure that the file is there where the renderer expects it to be.
Simple file names (no path) can be taken relative to the ChordPro file. This is not unlike automatic processing of audio files, and PDF/CSV pairs.
For a start, it's okay to only deal with simple file names and forget about the uri idea.

As for the values/ranges for each proposed parameter:

• parameter values are part of the parameter, separated by a =. No blanks.
  
• width: an integral number (pixels) >= 1, defaults to the actual width of the image. If it is too wide to fit, the image is scaled (keeping aspect ratio) to fit.
  
• height: similar to width. If both height and width are specified, aspect ratio may change.
  
• scale: scaling factor (fixed point decimal). If the resultant dimensions exceed the screen, scale to fit. If the height does not fit on the current page, make a new page. Default is to scale to fit, unless scale=0.
  
• center: if present the image will be centered on the screen, provided the actual width is smaller than the width of the screen.
  
• border: provide a border around the image. Default is no border (border=0). Just border without width is a 1-pixel border.
  

Does that make sense?
Note that screen width and height are subject to margins the MSPro may enforce.
Fallback: If an image cannot be found, act as if the {image...} was {comment: image...}.

[Zubersoft]

All of that sounds good to me. If the backup/restore becomes an important issue in the future, it can be revisited then.

[AndyL]

You might be able to help the backup/restore problem by having an "add image" button in the editor. This could copy the image to somewhere within the MSP file structure and generate the chordPro commands to point at it. Any images added outside this method would be fair game for ignoring in the backup process. Maybe generating a warning at the point of saving the ChordPro file so people know.

Andy

[Zubersoft]

That's a pretty good idea although it obviously adds a lot more work to set all that up in the editor. It also ties people to the MS Pro editor for adding images versus being able to do it from their PC (although if I add a text editor to the companion app, this could help). Also, if people are just importing a file they got from someone else, that wouldn't work as well. That brings up a different issue though of managing those image files during an import if MS Pro is currently managing files and needs to copy the imported file to the storage location. If the image command specifies a relative path, then either the user would be required to copy the image to the storage location or I would have to add additional code to process this all during an import.

[itsme]

What about reusing the "files" tab of the song editor to let the user add the image file to the library and handle it within the MSP library like any other file? Let that be the first step, then the MSP chordpro editor could take over the filename and (relative) path and the parameters as proposed by Sciurius can do the rest. Doesn't that sound easy and logical?

[NeoCZ]

Just want to bring this topic up. I would like to add an image into Chordpro file with important riff. I tried to use ChordPro image directive - https://www.chordpro.org/chordpro/Directives-image.html but it seems it's not supported in MSPro. Would it be possible to add support for this directive?

[Zubersoft]

It's certainly something I would like to add support for. There are some issues that could be presented though, such as: 

1) What happens if the library is synchronized to another library? Do I have to include the linked file as part of the MobileSheets library? If so, that presents some real problems as it's only processed while rendering the file, so I would then have to add it to a new database to track it most likely or do extra processing of chord pro files when synchronizing to see if they link to image files.

2) Similar to #1, what about library backup/restore?

3) Are you using a relative path or absolute path? I'm assuming this feature would only work well for users who manage their own files or have their storage location set to a more accessible folder than the default one. If a user lets MobileSheets manage their files but specifies a different storage location, then changes that storage location later, the link will be broken, so similar to #1 and #2, do I have to handle this appropriately or is on the user to handle this?

If I keep it simple and allow the image to be rendered but I require that the user be responsible for ensuring the file is available, then I can probably add this feature without too much difficulty. If I have to correctly handle library backups, synchronization, etc, then it's going to be more complicated and more analysis and design time will be required.

Mike

[sciurius]

Would the treatment of assets (e.g., images) be different from audio and midi files that are associated with songs?

[Zubersoft]

In a sense, yes, it would be, because I only process the audio file stuff once when the audio file is first imported. I also have a dedicated table for tracking those file paths. If I only process the image command the first time I read the chord pro file after import, that's one thing, but if I have to handle any potential changes to the image command, that's something entirely different. If the user just edits the chord pro file and specifies a different file, how should I go about handling that? Should I remove the file from the database/library that was linked and link the new file? If an absolute path is used instead of a relative path (something you can't do on Windows 10 I might add), do I have to go and update the chord pro file during a library sync, library backup, etc, so that the path will point to a relative path and can be processed properly? If I force users to only link to other files inside the MobileSheetsPro library so that i don't have to process all that differently, how do I enforce that for newly imported files? That doesn't seem like it would work too well in practice. 

I just think the whole thing is a huge headache unless I leave it up to users to manage their own files or urls are used instead of file paths (which then introduces other complexities unless the width/height options are not optional in the command so I can rely on that without having to parse the image dimensions). I think the feature becomes a lot less valuable though if I don't force it to be managed as part of the library. So it seems like if I force paths to be relative (by modifying the file itself to have the path I want), and I force the files to be copied into the storage location, then library backup/restore and synchronizing would work like expected. So it's doable, but it seems to me like it's going to be a considerable amount of work to support this for Android, Windows 10 and the companion app.

Mike

[sciurius]

Maybe it is feasible to first implement a limited form of support. For example, simple filenames only (no path, no url) and the user is responsible that this file exists in the same folder as the ChordPro file.
I don't use Companion so I don't know if it can transfer arbitrary files.

When the user edits the ChordPro file and changes the filename of an image she is on her own. If the song is displayed and the image cannot be found just show a grey area (if sizes were specified) with a missing image icon.

If this feature is too much of a pain to add to MSPro --- well, bad luck then. There are lots of other interesting features left.

In my collection of ChordPro songs, only a few use the {image} feature, and always to include a small piece of a score, e.g.

   

A possible future inline ABC feature could do that as well, eliminating the need for these images...

[NeoCZ]

I agree with sciurius how it might be implemented - image must be in the same folder as ChordPro file, user is responsible to put images there and if image isn't found, just display grey area with missing image icon or simple text like "Image xxx.png" not found.

Also if ABC or MusicXML is going to be supported in the future, images in ChordPro might be not needed anymore.