README
¶
go-ultrastar
This project provides multiple Go packages for working with UltraStar songs. Have a look at the Docs.
Packages
The main ultrastar package implements the main types for programmatically interacting with karaoke songs.
The txt subpackage implements a parser and a serializer for the UltraStar TXT format.
Installation
go get codello.dev/ultrastar
Quick Start
import (
"codello.dev/ultrastar"
"codello.dev/ultrastar/txt"
)
// Parse song from a file
file, _ := os.Open("some/song.txt")
defer file.Close()
song, err := txt.ReadSong(file)
// Do some transformations
song.Title = "Never Gonna Give You Up"
song.MusicP1.ConvertToLeadingSpaces()
// Work with GAP, VIDEOGAP, etc. using native Go types
song.Gap = 2 * time.Second
// The ultrastar package provides convenient types for Pitches, Beats, BPM, ...
song.MusicP1.Notes[2].Pitch = ultrastar.NamedPitch("F#2")
// Write song back to file
err = txt.WriteSong(file, song)
Have a look at the Docs to see everything you can do.
Documentation
¶
Overview ¶
Package ultrastar is a package for working with UltraStar songs. The package provides data types for working with songs and notes as well as some methods for typical transformations.
The github.com/Karaoke-Manager/go-ultrastar/txt subpackage implements a parser and serializer for the UltraStar TXT format.
Index ¶
- Constants
- Variables
- type BPM
- type Beat
- type Note
- type NoteType
- type Notes
- func (ns Notes) ConvertToLeadingSpaces()
- func (ns Notes) ConvertToTrailingSpaces()
- func (ns Notes) Duration(bpm BPM) time.Duration
- func (ns Notes) EnumerateLines(f func([]Note, Beat))
- func (ns Notes) LastBeat() Beat
- func (ns Notes) Len() int
- func (ns Notes) Less(i int, j int) bool
- func (ns Notes) Lyrics() string
- func (ns Notes) Offset(offset Beat)
- func (ns Notes) Scale(factor float64)
- func (ns Notes) ScaleBPM(from BPM, to BPM)
- func (ns Notes) Substitute(substitute string, texts ...string)
- func (ns Notes) Swap(i int, j int)
- type Pitch
- type Song
Examples ¶
Constants ¶
const MaxBeat = Beat(^uint(0) >> 1)
MaxBeat is the maximum value for the Beat type.
Variables ¶
var ( // ErrInvalidPitchName denotes that the named pitch was not recognized. ErrInvalidPitchName = errors.New("unknown pitch name") )
These known errors might be returned by some of the functions and methods in this package.
Functions ¶
This section is empty.
Types ¶
type BPM ¶
type BPM float64
BPM is a measurement of the 'speed' of a song. It counts the number of Beat's per minute.
func (BPM) Beats ¶
Beats returns the number of beats in the specified duration. The result is rounded down to the nearest integer. If b is invalid the result is undefined.
type Beat ¶
type Beat int
A Beat is the measurement unit for notes in a song. A beat is not an absolute measurement of time but must be viewed relative to the BPM value of the [Music].
type Note ¶
type Note struct {
// Type denotes the kind note.
Type NoteType
// Start is the start beat of the note.
Start Beat
// Duration is the length for which the note is held.
Duration Beat
// Pitch is the pitch of the note.
Pitch Pitch
// Text is the lyric of the note.
Text string
}
A Note represents the smallest timed unit of text in a song. Usually this corresponds to a syllable of text.
func (Note) Lyrics ¶
Lyrics returns the lyrics of the note. This is either the note's Text or may be a special value depending on the note type.
func (Note) String ¶
String returns a string representation of the note, inspired by the UltraStar TXT format. This format should not be relied upon. If you need consistent serialization use the github.com/Karaoke-Manager/go-ultrastar/txt subpackage.
Example ¶
n := Note{
Type: NoteTypeGolden,
Start: 15,
Duration: 4,
Pitch: 8,
Text: "Go",
}
fmt.Println(n.String())
Output: * 15 4 8 Go
type NoteType ¶
type NoteType byte
The NoteType of a Note specifies the input processing and rating for that note.
const ( // NoteTypeLineBreak represents a line break. // Line Break notes do not have a Duration or Pitch. NoteTypeLineBreak NoteType = '-' // NoteTypeRegular represents a normal, sung note. NoteTypeRegular NoteType = ':' // NoteTypeGolden represents a golden note that can award additional points. NoteTypeGolden NoteType = '*' // NoteTypeFreestyle represents freestyle notes that are not graded. NoteTypeFreestyle NoteType = 'F' // NoteTypeRap represents rap notes, where the pitch is irrelevant. NoteTypeRap NoteType = 'R' // NoteTypeGoldenRap represents golden rap notes (also known as Gangsta notes) // that can award additional points. NoteTypeGoldenRap NoteType = 'G' )
These are the note types supported by this package. These correspond to the note types supported by UltraStar.
func (NoteType) IsFreestyle ¶
IsFreestyle determines if a note is a freestyle note.
func (NoteType) IsLineBreak ¶
IsLineBreak determines if a note is a line break.
type Notes ¶
type Notes []Note
Notes represents a sequence of notes in a karaoke song. This usually corresponds to the notes sung by a single player.
A Notes value does not know about the relative mode of UltraStar files. All times in a Notes value are assumed to be absolute. The github.com/Karaoke-Manager/go-ultrastar/txt package can parse and write UltraStar files in absolute or relative mode.
All functions operating on a Notes value must maintain the invariant that all notes are sorted by their respective Start values. Notes implements sort.Interface which can restore this property.
func (Notes) ConvertToLeadingSpaces ¶
func (ns Notes) ConvertToLeadingSpaces()
ConvertToLeadingSpaces ensures that the text of notes does not end with a whitespace. It does so by "moving" the whitespace to the neighboring notes. Spaces are not moved across line breaks, so Notes before line breaks and the last note will have trailing spaces removed.
Only the space character is understood as whitespace.
func (Notes) ConvertToTrailingSpaces ¶
func (ns Notes) ConvertToTrailingSpaces()
ConvertToTrailingSpaces ensures that the text of notes does not start with a whitespace. It does so by "moving" the whitespace to the neighboring notes. Spaces are not moved across line breaks, so Notes after line breaks and the first note will have leading spaces removed.
Only the space character is understood as whitespace.
func (Notes) Duration ¶
Duration calculates the absolute duration of m, using the specified BPM. The duration ignores any trailing line breaks.
func (Notes) EnumerateLines ¶
EnumerateLines calls f for each line of the lyrics. A line are the notes up to but not including a line break. The Start value of the following line break is passed to f as a second parameter. If a song does not end with a line break the [Music.LastBeat] value will be passed to f.
func (Notes) LastBeat ¶
LastBeat calculates the last meaningful Beat in m, that is the last beat of the last non line break note.
func (Notes) Len ¶
Len returns the number of notes in the slice.
This is part of the implementation of sort.Interface.
func (Notes) Less ¶
The Less function returns a boolean value indicating whether the note at index i starts before note at index j.
This is part of the implementation of sort.Interface.
func (Notes) Lyrics ¶
Lyrics generates the full lyrics of ns. The full lyrics is the concatenation of the individual Note.Lyrics values.
func (Notes) Scale ¶
Scale rescales all notes, durations and BPM changes by the specified factor. This will increase or decrease the duration of m by factor. All times will be rounded to the nearest integer.
func (Notes) ScaleBPM ¶
ScaleBPM recalculates note starts and durations to fit the specified target BPM. After this method returns ns.Duration(to) is approximately equal to ns.Duration(from) before this method was called. Values are rounded to the nearest integer.
func (Notes) Substitute ¶
Substitute replaces note texts that exactly match one of the texts by the specified substitute text. This can be useful to replace the text of holding notes.
type Pitch ¶
type Pitch int
A Pitch represents the pitch of a note.
func NamedPitch ¶
NamedPitch works like PitchFromString but panics if the pitch cannot be parsed. This can be useful for testing or for compile-time constant pitches.
func PitchFromString ¶
PitchFromString returns a new pitch based on the string representation of a pitch.
func (Pitch) NoteName ¶
NoteName returns the human-readable name of the pitch. The note naming is not very sophisticated. Only whole and half steps are supported and note names use sharps exclusively. So a D flat and a C sharp will both return "C#" as their note name.
Example ¶
fmt.Println(NamedPitch("Gb4").NoteName())
Output: F#
func (Pitch) Octave ¶
Octave returns the scientific octave of a pitch.
Example ¶
fmt.Println(Pitch(0).Octave())
Output: 4
type Song ¶
type Song struct {
// References to other files.
AudioFileName string
VideoFileName string
CoverFileName string
BackgroundFileName string
// The BPM of the song.
BPM BPM
// A delay until Beat 0 of the song's notes.
Gap time.Duration
// A delay until the video starts.
VideoGap time.Duration
// UltraStar will jump into the song at this time.
Start time.Duration
// UltraStar will stop the song at this time.
End time.Duration
// If specified the preview will start at this time.
PreviewStart time.Duration
// In medley mode this is the start of the song.
MedleyStartBeat Beat
// If medley mode this is the end of the song.
MedleyEndBeat Beat
// Disable medley and preview calculation.
NoAutoMedley bool
// Song metadata
Title string
Artist string
Genre string
Edition string
Creator string
Language string
Year int
Comment string
// Name of player 1
DuetSinger1 string
// Name of player 2
DuetSinger2 string
// Any custom tags that are not supported by this package.
// CustomTags are case-sensitive.
// Note however, that the [codello.dev/ultrastar/txt] package normalizes all tags to upper case.
CustomTags map[string]string
// Notes of player 1.
NotesP1 Notes
// Notes of player 2. Any non-nil value indicates that this is a duet.
NotesP2 Notes
}
A Song is an implementation of an UltraStar song. This implementation directly supports many of the known fields for songs, making it convenient to work with. Known fields are normalized to standard Go types, so you don't have to deal with the specifics of #GAP, #VIDEOGAP and so on.
The Song type does not support parsing or serialization. To parse and write songs use the github.com/Karaoke-Manager/go-ultrastar/txt package.
Source Files
Directories