gsapi.GSPattern module

class gsapi.GSPattern.GSPatternEvent(startTime=0, duration=1, pitch=60, velocity=80, tag=None, originPattern=None)

Represent an event of a GSPattern with startTime, duration, pitch, velocity and tag variables.

Class variables:

startTime: startTime of event duration: duration of event pitch: pitch of event velocity: velocity of event tag: any hashable object representing the event , i.e strings, tuples, objects (but not lists) originPattern : keeps track of origin pattern for events generated from pattern, example a chord event can still access to its individual components via originPattern (see GSPattern.generateViewpoints)

hasOneCommonTagWith(event)

Compare tags between events.

Parameters:event – event to compare with Returns:True if at least one tag is equal

hasOneOfTags(tags)

Compare this event’s tags with a list of possible tag.

Parameters:tags – list of tags to compare with Returns:True if at least one tag is equal

tagIs(tag)

Compare this event’s tag with a a given tag.

Parameters:tag – tag to compare with Returns:True if all event tag is equal to given tag

allTagsAreEqualWith(event)

Compare this event’s tag with an other event.

Parameters:event – event to compare with Returns:True if tags are equal

getEndTime()

Return the time when this events ends

Returns:The time when this event ends

copy()

Copy an event.

Returns:A deep copy of this event to be manipulated without changing original.

cutInSteps(stepSize)

Cut an event in steps of stepsize length.

Parameters:stepSize – the desired size of each produced events Returns:a list of events of length stepSize

containsTime(time)

Return true if event is active at given time

Parameters:time – time to compare with

class gsapi.GSPattern.GSPattern(duration=0, events=None, bpm=120, timeSignature=(4, 4), key='C', originFilePath='', name='')

Class representing a pattern made of GSPatternEvent. Holds a list of GSEvents and provide basic manipulation function.

Class Variables:

duration: length of pattern. Usually in beats, but time scale is up to

the user (it can be useful if working on 32th note steps).

events: list of GSPatternEvent for this pattern. bpm: initial tempo in beats per minute for this pattern (default: 120). timeSignature: list of integers representing the time signature,

i.e [numerator, denominator]. startTime : startTimeof pattern (useful when splitting in sub patterns) viewPoints: dict of GSViewPoint

applyLegato(usePitchValues=False)

this function supress the possible silences in this pattern by stretching consecutive identical events

(i.e identical tags or pitch values)

Parameters:usePitchValues – should we consider pitch numbers instead of tags (bit faster)

transpose(interval)

Transposes a GSPattern to the desired interval

Parameters:

• interval – transposition factor in semitones
• can be a positive or negative int) ((it) –

setDurationFromLastEvent(onlyIfBigger=True)

Sets duration to last event NoteOff

Parameters:onlyIfBigger – update duration only if last Note off is bigger

if inner events have a bigger time span than self.duration, increase duration to fit

reorderEvents()

Ensure than our internal event list events is time sorted. It can be useful for time sensitive events iteration.

getLastNoteOff()

Gets last event end time

Returns:lastNoteOff, i.e the time corresponding to the end of the last event

addEvent(event)

Add an event increasing duration if needed.

Parameters:event – the GSPatternEvent to be added

removeEvent(event)

remove given event :param event: the GSPatternEvent to be added

removeByTags(tags)

Remove all event(s) in a pattern with specified tag(s).

Parameters:tags – list of tag(s)

quantize(stepSize, quantizeStartTime=True, quantizeDuration=True)

Quantize events.

Parameters:

• stepSize – the duration that we want to quantize to
• quantizeDuration – do we quantize duration?
• quantizeStartTime – do we quantize startTimes

timeStretch(ratio)

Time-stretch a pattern.

Parameters:ratio – the ratio used for time stretching

getStartingEventsAtTime(time, tolerance=0)

Get all events activating at a given time.

Parameters:

• time – time asked for
• tolerance – allowed deviation of start time

Returns:

list of events

getActiveEventsAtTime(time, tolerance=0)

Get all events currently active at a givent time.

Parameters:

• time – time asked for
• tolerance – admited deviation of start time

Returns:

list of events

copy()

Deepcopy a pattern

getACopyWithoutEvents()

Copy all fields but events. Useful for creating patterns from patterns.

getAllTags()

Returns all used tags in this pattern.

Returns:set of tags composed of all possible tags

getAllPitches()

Returns all used pitch in this pattern.

Returns:list of integers composed of all pitches present in this pattern

getPatternWithTags(tagToLookFor, exactSearch=True, makeCopy=True)

Returns a sub-pattern with the given tags.

Parameters:

• tagToLookFor – tag,tags list or lambda expression (return boolean based on tag input): tags to be checked for
• exactSearch – bool: if True the tags argument can be an element of tag to look for, example : if we set tags=’maj’,an element with tag (‘C’,’maj’) will be valid
• makeCopy – do we return a copy of original events (avoid modifying originating events when modifying the returned subpattern)

Returns:

a GSPattern with only events that tags corresponds to given tagToLookFor

getPatternWithPitch(pitch, makeCopy=True)

Returns a sub-pattern with the given pitch.

Parameters:

• pitch – pitch to look for
• makeCopy – do we return a copy of original events (avoid modifying originating events when modifying the returned subpattern)

Returns:

a GSPattern with only events that pitch corresponds to given pitch

getPatternWithoutTags(tagToLookFor, exactSearch=False, makeCopy=True)

Returns a sub-pattern without the given tags.

Parameters:

• tagToLookFor – tag or tag list: tags to be checked for
• exactSearch – bool: if True the tags have to be exactly the same as tagToLookFor, else they can be included in events tag
• makeCopy – do we return a copy of original events (avoid modifying originating events when modifying the returned subpattern)

Returns:

a GSPattern with events without given tags

alignOnGrid(stepSize, repeatibleTags=['silence'])

Align this pattern on a temporal grid. Very useful to deal with step-sequenced pattern: - all events durations are shortened to stepsize - all events startTimes are quantified to stepsize

RepeatibleTags allow to deal with silences type of events: - if a silence spread over more than one stepsize, we generate an event for each stepSize

Thus each step is ensured to be filled with one distinct event at least.

Parameters:

• stepSize – temporal definition of the grid
• repeatibleTags – tags

removeOverlapped(usePitchValues=False)

Remove overlapped elements.

Parameters:usePitchValues – use pitch to discriminate events

getAllIdenticalEvents(event, allTagsMustBeEquals=True)

Get a list of event with same tags.

Parameters:

• event – event to compare with
• allTagsMustBeEquals – shall we get exact tags equality or be fine with one common tag (valable if tags are tuple)

Returns:

list of events that have all or one tags in common

getFilledWithSilences(maxSilenceTime=0, perTag=False, silenceTag='silence')

fillWithSilences(maxSilenceTime=0, perTag=False, silenceTag='silence', silencePitch=0)

Fill empty time intervals (i.e no event) with silence event.

Parameters:

• maxSilenceTime – if positive value is given, will add multiple silence of maxSilenceTime for empty time larger than maxSilenceTime
• perTag – fill silence for each Tag
• silenceTag – tag that will be used when inserting the silence event
• silencePitch – the desired pitch of new silences events

fillWithPreviousEvent()

Fill gaps between onsets making longer the duration of the previous event.

getPatternForTimeSlice(startTime, length, trimEnd=True)

Returns a pattern within given timeslice.

Parameters:

• startTime – start time for time slice
• length – length of time slice
• trimEnd – cut any events that ends after startTime + length

Returns:

a new GSpattern within time slice

toJSONDict(useTagIndexing=True)

Gives a standard dict for json output. Args: useTagIndexing: if true, tags are stored as indexes from a list of all tags (reduce size of json files)

fromJSONDict(json, parentPattern=None)

Loads a json API dict object to this pattern

Parameters:json – a dict created from reading json file with GS API JSON format

splitInEqualLengthPatterns(desiredLength, viewpointName=None, makeCopy=True, supressEmptyPattern=True)

Splits a pattern in consecutive equal length cuts.

Parameters:

• desiredLength – length desired for each pattern
• viewpointName – if given, slice the underneath viewpoint instead
• makeCopy – returns a distint copy of original pattern events, if you don’t need original pattern anymore setting it to False will increase speed

Returns:

a list of patterns of length desiredLength

generateViewpoint(name, descriptor=None, sliceType=None)

generate viewpoints in this GSPattern :param name: name of the viewpoint generated , if name is one of [“chords”,] it will generate the default descriptor :param descriptor: if given it’s the descriptor used :param sliceType: type of slicing to compute viewPoint:

if integer its duration based see:splitInEqualLengthPatterns if “perEvent” generates new pattern every new events startTime, if “all” get the whole pattern (generate one and only viewPoint value)

printASCIIGrid(blockSize=1)