Release Notes

( ! = fix ) ( + = add ) ( ~ = change )

Supports the latest STABLE, OFFICIAL RELEASE versions of Unity v2017.4+.

NOTE: Some add-ons/integrations may require newer Unity versions. Tested on Windows, Mac, Linux, Android, iOS, and Universal Windows Platform. WebGL lipsync is only supported when combined with our Amplitude asset.

!!! ALWAYS BACKUP YOUR PROJECT BEFORE INSTALLING A NEW VERSION !!!

Version 2.5.0 - 2020-09-03:

RECOMMENDED for use in NEW projects. For existing projects, re-configuration will be required in the Eyes module and the underlying Eyes API has some breaking changes.

SALSA:

+ (Experimental) Advanced Dynamics Silence Analyzer helps detect more nuance in audio and provides a better perceived accuracy. Silence processing can be delegated to your own calculations if desired.

NOTE: This does not currently work with microphone (or other circular) buffers.

+ New delegate maps for audio (clip) processing.

+ New delegate map for external analysis value retrieval.

+ Delegate mappings are visible at runtime for troubleshooting purposes.

+ Visualized viseme firing now available in Trigger Display Mode.

NOTE: Unity typically does not support live updates in the Inspector, but does update when the scene or Inspector values have changed. Enable SALSA Settings > "Show Analysis Value" to force regular updates to the visualized viseme display.

+ Expand viseme to show components in Trigger Display Mode.

+ Components are now tested for configuration-error null-ref prior to registration in the QueueProcessor.

+ Option to suppress SALSA configuration-error null-ref warning messages. (References Section)

+ Better UMA Expression Player animations. UMA shapes are more smoothly animated and animation blending greatly reduces jittery look-and-feel.

~ Data Analysis: Auto Adjust Bias processing has been tuned to lower look-ahead values for higher sample rates.

~ Salsa.globalFrac now affects Advanced Dynamics and is now enabled in the Inspector even when AdvDynamics is enabled. (Settings: Global Overrides)

~ Emphasis emotes are now fired whenever the threshold is exceeded. Previously, they were only calculated when the triggered viseme was not repeated.

~ Adjusted default value for emphasisTrigger to 0.0f.

~ Settings: Secondary Mix and 2D Rollback options are now mutually exclusive in the Inspector.
! Salsa.VisemeTriggered event now only fires when a non-silence viseme is triggered.

~ Bunches and bunches of internal refactoring and minor bug fixes...

EmoteR:

+ Emphasis emotes have been divided into always fired and randomly fired options. Emphasis emotes configured to always fire are excluded from the random emphasis emote calculations.

+ Random emphasis emotes can now be configured to fire multiple emotes per Salsa tick cycle.

+ Components are now tested for configuration-error null-ref prior to registration in the QueueProcessor.

+ Option to suppress EmoteR configuration-error null-ref warning messages. (References Section)

+ New Follow Offset bone component option. Allows an offset to follow external influence throughout the animation instead of statically from the trigger point.

+ Better UMA Expression Player animations. UMA shapes are more smoothly animated and animation blending greatly reduces jittery look-and-feel.

~ Adjusted default value for emphasisChance to 1.0f.

~ Bunches and bunches of internal refactoring and minor bug fixes...

Eyes:

+ System Properties - Warn on Null-Refs displays console warnings when linked references suddenly goe missing, such as with runtime character reconfigurations.

+ Head Configuration - Update Fwd/Center Refs continuously updates the forward and center reference rotations to match the character root rotation.

+ Head Configuration - Use Animator Controlled MergeBack. Though it is recommended to use the global option (Merge with influencer) available on the QueueProcessor component, this option provides the same capability at the component level.

+ Head Configuration - Rotational offsets are now calculated automatically when setting up your character. This means accurate tracking regardless of your bone orientations and no more corrective hierarchy being added to your character.

~ Head Configuration - Fix Axis / Restore Axis is deprecated, this feature was replaced with a rotation offset that is calculated automatically. The old method will remain in place for one update, giving you time to use the Restore Axis option to remove any corrective hierarchy and stop using this feature.

~ Head Configuration - When using the Bone_Rotation_Z template with sprite flipping and facing camera, setting a random distance from -value to +value will create new head targets on either side of the character using the min/max extents, not a range as is the case in all other scenarios.

+ Eye Configuration - Use Animator Controlled MergeBack. Though it is recommended to use the global option (Merge with influencer) available on the QueueProcessor component, this option provides the same capability at the component level.

+ Eye Configuration - Rotational offsets are now calculated automatically when setting up your character. This means accurate tracking regardless of your bone orientations and no more corrective hierarchy being added to your character.

~ Eye Configuration - Fix Axis / Restore Axis is deprecated, this feature was replaced with a rotation offset that is calculated automatically. The old method will remain in place for one update, giving you time to use the Restore Axis option to remove any corrective hierarchy and stop using this feature.

~ Eye Configuration - Previously when an expression or component required directional awareness, we used a fixed magic name field. This has been replaced with a new Direction Type enum field that shows up under the component name field in the inspector whenever directional awareness applies. The options include: None, Upper Left, Upper, Upper Right, Left, Center, Right, Lower Left, Lower, Lower Right. For example, this field is used to determine Upper and Lower eyelids, the eye blendshape directions Upper, Right, Lower, Center, as well as the directional orientation for Sectors and Swap when using sprites, materials, and textures, etc.

~ Eye Configuration - The Bone_Position template for positional tracking. Defaults to two eye expressions with two Transform components each. One component uses the Direction Type Upper, and the other component uses the Direction Type Right, each should be linked to the same eye. When setting up a Bone_Position template you must capture the maximum upper and maximum right positions, the system will use these to calculate the maximum lower and maximum left extents for your total eye range of motion. This makes the Bone_Position tracking axis agnostic.

~ Eye Configuration - Range of Motion has been removed since this is now determined by the Bone_Position template capture extents.

~ Eye Configuration - Porportional Movement has been removed since this is now determined by the Bone_Position template capture extents.

~ Eye Configuration - Component name fields no longer use magic locked names for directional awareness, this has been offloaded to the new Direction Type field in all Eyes modules where directional awareness is necessary.

+ Eyelid Configuration - Rotational offsets are now calculated automatically when setting up your character. This means accurate tracking regardless of your bone orientations and no more corrective hierarchy being added to your character.

~ Eyelid Configuration - Fix Axis / Restore Axis is deprecated, this feature was replaced with a rotation offset that is calculated automatically. The old method will remain in place for one update, giving you time to use the Restore Axis option to remove any corrective hierarchy and stop using this feature.

~ Eyelid Configuration - Previously when an expression or component required directional awareness, we used a fixed magic name field. This has been replaced with a new Direction Type enum field that shows up under the component name field in the inspector whenever directional awareness applies. The options include: None, Upper Left, Upper, Upper Right, Left, Center, Right, Lower Left, Lower, Lower Right. For example, this field is used to determine Upper and Lower eyelids, the eye blendshape directions Upper, Right, Lower, Center, as well as the directional orientation for Sectors and Swap when using sprites, materials, and textures, etc.

~ Eyelid Configuration - Using the Copy button in the inspector to copy eyelid blink expressions to eyelid tracking expressions no longer warns that you are about to overrite your eyelid tracking controllers. There's a bug in unity 2020 that logs bogus erros to the console, so for now the confirmation prompt has been removed.

+ API - LookForward() Moves random interntal targets to the characters forward position.

+ API - BuildEyelidTemplate(EyelidTemplates eyelidTemplate, EyelidSelection eyelidSelection) Added overload to include an EyelidSelection parameter. Options are Both, Upper, Lower. Use Upper if you have combined eyelids. No EyelidSelection parameter default to Upper and Lower controllers.

~ API - SetEyelidShapeSelection(EyelidSelection selection) Removed, use the new parameter in the BuildEyelidTemplate overload function.

QueueProcessor:

+ New QueueProcessor.FlushQueue() to programmatically remove all queued items.

+ Queue items are now tested for configuration-error null-ref and if invalid, are removed from the Queue.

+ UMA Controller now has dynamic influence detection just like Shape and Bone controllers.

+ (Experimental) Ignore Time Scaling - enable this option to ignore any time scaling in effect.

~ Reworked external influence processing -- much better detection of influence and processing merge-back. Now computed in the QueueProcessor vice the expression controller.

Suite:

+ Preprocessor define symbol "CMS_SALSA".

~ Version display now shows build number element.

---

Version 2.4.1 - 2020-04-02:

SALSA:

+ New VisemeTriggered event.
+ Access to AnimatorController and EventController types in viseme component setup.

---

Version 2.4.0 - 2020-03-19:

SALSA:

+ Modular/switchable audio analyzers. Custom analyzers may now be plugged into SALSA to generate audio analysis values.
~ Secondary Mix settings have been re-worked to operate using the primary triggered viseme timings and handler. A much smoother and more consistent operation.
! Trigger distribution buttons display better in Unity 2019.3+
! Removed residual Unity.Microphone class from core and inspector code.
! Salsa.autoAdjustAnalysis is now only available and effective if !Salsa.useExternalAnalysis.

EmoteR:

~ Emoter name field moved to the References section.

Suite:

+ New version number display label at top of each main module.

---

Version 2.3.1 - 2020-02-11:

NOTE: This version (v2.3.0+) introduces some major changes in the underlying code. Much effort has been spent to maintain backwards compatibility; however, in some cases this was not possible. As a result, several add-ons required updates to work with the new version. All OneClicks and the SalsaMicInput add-on have specific updates for SALSA Suite v2.3.0+ and have been like-versioned as v2.3.0+. OneClickBase did not require an update. Please ensure you use the appropriate OneClick/MicInput add-ons for your version of SALSA Suite.

Eyes:

+ API support changes for visual-code/design add-ons. REQUIRES updated, like-versioned (v2.3.1+) visual-code/design add-ons. Please read the requirements for each add-on.
! Fixes known inspector bugs.

---

Version 2.3.0 - 2020-02-03:

Suite:

+ Hierarchical layering of queue components. This is a major re-write of parts of the QueueProcessor and certain ExpressionComponent implementations. The QueueProcessor now maintains several queues which may hold the same controllers from other controller types (i.e. Blink vs Emote). This implementation allows both to exist and (if configured) merge back to a lesser controller from a higher controller.

For example: an Emote configured with a shape of blink set to maintain 50% for a tired look can be intermittently interrupted with an actual eye blink -- overriding the emote, but returning to the emote's 'sleepy' state.

Priority overwriting of controller values: (highest > lowest)
Blinks > Lipsync > Emotes > Lids > Eyes > Heads

+ Over/Under-driving of blendshapes. The shape controller has been updated to allow over/under-driving blendshapes in versions of Unity supporting the feature (Unity 2018.3+). This also requires the legacy clamping option to be disabled in Unity.

+ 2D render pipeline texture setting property: Added salsa settings configurator to allow changing the property name. Allows LWRP property to be specified (_BaseMap vs _MainTex)
+ Component persistence now honors all controller types vice bone-only.
+ External animation MergeBack now offered for shapes and bones in all modules.
+ Automatic/Dynamic external influence available as a global setting in QueueProcessor and applied to all components. No longer necessary to "enable" animator controlled and mergeback. ~ QueueProcessor Inspector changes to accommodate new queue hierarchy lists.
~ Shape processing improved with fractional update registrations for smoother transitions vice popping to new value.

SALSA:

~ Advanced Dynamics improved with smoother micro transitions vice popping to the new value.
~ Removed the Unity Microphone class reference from the core code to eliminate improper permissions requests in builds where the OS tracks and alerts to permission usage (and the microphone is not used).

NOTE: This change requires an update to SalsaMicInput (to v2.3.0+) or equivalent code to operate correctly with a microphone. SALSA now has a field (Salsa.microphoneRecordHeadPointer) which must be updated via another process for correct audio analysis computations. The new SalsaMicInput (v2.3.0+) addon includes a sample helper script which updates SALSA with the microphone's current record head position. The helper script is automatically applied to the same GameObject when 'Link with SALSA' is enabled. It may also be removed if you are using your own script to update SALSA.microphoneRecordHeadPointer.

! SALSA OnDisable now clears persistence in the Queue to cleanup and remove component items.

EmoteR:

~ EmoteR: bone controller re-trigger prior to completion of animation cycle now properly reads and applies the previous controller's position instead of restarting the animation from beginning.
! Emoter pools now properly reset when performing: runtime-copy > editor-paste > re-run.
! Persistent bones should now update positions from previously applied lerps vice from current animator transform influence.

Eyes:

+ Disabling of individual components (Head, Eyes, Blink[lids], Track[lids]) and removal of persistent components from the Queue.
+ New Blink component type and interface changes. Lid tracking and blink setup are now separate. The new eyelid tracking EyeExpression list is called "tracklids".
+ public function CopyBlinkToTrack() - Copies the blink controllers to the tracking controllers.
+ public function EnableAll(bool status) - Enable/disable all Eyes module section components (head, eyes, blink, eyelid tracking).
+ public function EnableHead(bool status) - Enable/disable the head section components.
+ public function EnableEye(bool status) - Enable/disable the eye section components.
+ public function EnableEyelidBlink(bool status) - Enable/disable the blink section components.
+ public function EnableEyelidTrack(bool status) - Enable/disable the eyelid tracking section components.
~ The previous "eyelid" EyeExpression list has been renamed to "blinklids". This was done to accommodate the separation of the eyelid tracking and eyelid blink controllers.
~ The AddEyelidShapeExpression function now requires an EyeExpression list reference parameter.
~ The [Enable Tracking] checkbox was removed since this is now it's own component section and controlled by they [Enable Track Processing] component state.

---

Version 2.2.3 - 2019-10-07:

EmoteR:

! Emote delay timing no longer affects the animation OFF phase.

---

Version 2.2.2 - 2019-09-26:

NOTE: There are two template files in the Examples > Scripts folder (SALSA_Template_EventControllerSubscriber, SALSA_Template_SalsaEventSubscriber) that demonstrate how the events can be used. The demo boxhead scene also implements the SALSA events template, writing to the console when SALSA starts/stops SALSAing.

• The SALSA event template component simply needs to be dropped on an object and linked to a SALSA component -- this simple template will then write to the console as the SALSA processing state changes.
• The EventController event template operates similarly -- add the component to any game object. To configure it, simply enter the EventIdentifier string that matches the controller configuration. It will subscribe to the EventController events and filter delegate processing according to the identifier string.

Suite:

~ Inspector adjustments to more cleanly work with narrow inspector width changes (SALSA/EmoteR).
~ Cleanup and optimizations to the QueueProcessor.

SALSA:

+ New Salsa.IsSALSAing property to determine if SALSA is "talking" or not. See API documentation for more information.
+ Started/StoppedSalsaing C# events added.
+ Global Overrides (in Settings) for timings and easings.
+ New slider mode for Global timings override. Simplified timings adjustment and experimentation.
~ Removed Settings > Experimental > MergeBack (no implementation benefit at this time).
! On removal of SALSA from editor or programmatically, link-indication in EmoteR is now updated in Editor.

EmoteR:

+ Option to exclude emotes from Hold-Variation calcs on per emote basis.
+ New delay timings option. Delays start timing for an emote component, for example: "stick-out-tongue" -- start open mouth, delay tongue out until mouth open.
+ Repeater Emotes: new initial animation timing options. Repeaters will start their first animation according to the selected rule.

+ New Controllers:

• AnimatorController - allows controlling (bool, float, int, trigger) Animator parameters.

• EventController - introduces C# events for:

  • EventController.AnimationStarting - has started animating in the ON direction.
  • EventController.AnimationON - has finished animating (or has been interrupted) in the ON direction.
  • EventController.AnimationEnding - has started animating in the OFF direction.
  • EventController.AnimationOFF - has finished animating (or has been interrupted) in the OFF direction.

Version 2.1.2 - 2019-09-05:

! Persistence base calculations were being applied in non-persistence-enabled settings. Caused an increase in perceived accuracy at expense of slight jittery appearance.

Version 2.1.1 - 2019-09-04:

• Experimental features should only be used when advised to do so.

SALSA:

+ Experimental options for special Queue handling: persistence and merge-back; initial support for blendshape persistence from SALSA configurations potentially help control jittery playback when blendshapes are modified in animations external to the Suite.
~ Selecting "Wait for AudioSource" then adding a source manually to the object now deselects wait and links up the audio source.
~ Multi-EmoteR configurations now display dropdown selection option at all times.
~ Selecting wait or external now hides the other.
~ Play/pause/stop buttons now only appear if editor is playing and an audiosource is linked with a clip. "No Clip" is displayed when and AudioSource exists without a linked clip.
! Selecting wait, now appropriately clears the background color after the target box is drawn.

Eyes:

+ New regex search arrays for OneClick flexibility/support in FindTransform() and FindBlendIndex().
~ Renamed head "Rotation Clamp" tip typo "ensure handom generation" to "ensure random generation."
~ Renamed "Random Blink" label to "Random" for inspector consistency.
~ Renamed "Blink Timer" label to "Timer" for inspector consistency.
! On a character with head and eyes configured, disabling the head meant the random eye Fov Degrees option was not visible.
! The track Eyes option wasn't visible in the inspector when using the UMA template.
! Yellow eye gizmo line calculations were wrong for blendshape-based characters.

Version 2.1.0 - 2019-07-24:

• Update required for UMA OneClick.
• Update required for OneClickBase v2.1.5.

Suite:

ControllerType:UMA --
+ new ExpressionController:UmaController
+ new UmaUepProxy to act as controller for the UMA controller type. Does not require UMA in project.
+ new UmaUepEditorPreviewTwirler to act as target to apply change to in the editor to allow UMA preview mode to work in editor.
ControllerType:Texture --
+ Material targeting in multi-material renderer setups.
+ Backup/Restore of textures on multi-material renderers.
+ Selective restore of texture on multi-material renderer.
~ QueueProcessor: no longer clamps01 on delta; now clamps to min/max extent values to work with UMA expression ranges [-1 .. 1] (or any other non-01 range requirements).
~ Removed debug log of preview toggle.
! Editor begin change check in wrong location.

SALSA:

+ New public property to read private cachedAnalysisValue (CachedAnalysisValue).
+ New public property to read private isSalsaProcessing state (IsSalsaProcessing).
+ Unfold button in visemes (compliment to Fold).
+ exposed property for the activated trigger (prevTriggeredIndex) as TriggeredIndex.

EmoteR:

+ Unfold button in visemes (compliment to Fold).
+ New public method to update specialty emote lists (random, emphasizer, repeater) for runtime configuration.

Eyes:

+ UMA template for Eyelids.
~ Runtime blink controller update now performed as part of controller update.
! Eyelid runtime controllers now cleared to reset instead of appending to existing list.
! Eyes now uses correct renderer for texture controller.

---

Version 2.0.1 - 2019-07-07:

• Update required for OneClick runtime configuration setups.
• Required for OneClickBase v2.1.3.

Suite

+ New menu option to get new OneClicks/Add-ons.
~ Removed debug logs of bone store/update info.

SALSA

+ API: Exposed property for the activated trigger (prevTriggeredIndex) as TriggeredIndex. + New option to scale external analysis values.
+ VU meter now displays red when analysis value == 1.0f.
~ When using external analysis values, no longer display linear scaling unless scaleExternalAnalysis is enabled.
~ VU display now only visible during runtime and has 'enable' option for better inspector performance when VU not needed.
! Runtime application of SALSA OneClicks now properly controls initialization with first LateUpdate() loop processing a prevTriggeredIndex.
! VU meter value now updates in real-time.

EmoteR

+ API: UpdateEmoteLists() - update specialty emote lists (random, emphasizer, repeater) for runtime configuration.

Eyes

+ Added eye gizmo icon to simplify scene selection when adjusting.
+ API: UpdateRuntimeBlinkControllers() - for updating the blink controllers at runtime.
+ API: FindBlendIndex(SkinnedMeshRenderer smr, string regexSearch) - for regex blendshape name search.
~ API: FindTransform(Transform charRoot, string regexSearch) - now uses regex Transform name search.
~ Eye template label renamed from 'Eye Template' to 'Eye Templates' to match the other sections.
! Head, Eye, and Eyelid section header was not setting error state correctly for all scenarios.
! Editor-based mecanim override option was not available in certain situations.
! Eyelid runtime controller now properly sets/resets eyelid controllers.

---

Version 2.0.0-initial - 2019-06-15:

• SALSA, EmoteR, Eyes: First build released to the Unity Asset Store.