Visemes Converter Tool — Documentation
Blender add-on for generating VRChat visemes from MMD blendshapes and for converting shape key names to Japanese MMD format.
Version: 2.0.0
Minimum Blender: 3.0.0
UI Location: View3D › Sidebar (N) › Visemes Tool
Category: Rigging
Installation
Edit > Preferences > Add-ons > Install- Select the
visemes.py file (or the zipped folder)
- Enable the add-on from the list
Project Structure
Modules
visemes.py
Add-on entry point. Contains bl_info, the _CLASSES list of all classes to register, _MMD_PROPS with the dynamic MMD property names, and the register() / unregister() functions that manage the add-on lifecycle in Blender.
utilities/constants.py
| Name |
Type |
Description |
MMD_VISEME_COUNT |
int |
Number of primary MMD visemes (あいうえお = 5) |
MMD_SEP_1 |
str |
Separator shape key name for visemes (---MMD Visemes---) |
MMD_SEP_2 |
str |
Separator shape key name for other expressions (^MMD Visemes / Other v) |
MMD_CANDIDATES |
dict |
Candidate names for auto-detection of source shape keys (keys: a, o, ch, blink) |
utilities/functions.py
| Name |
Type |
Description |
MMD_JP_MAPPING |
list[tuple] |
List of 15 entries (jp_name, suffix, en_label, candidates) mapping English/VRChat shape keys to Japanese MMD names |
VRC_ORDER |
list[str] |
Standard VRChat order for the 16 visemes (vrc.v_sil … vrc.blink) |
build_viseme_map(shape_a, shape_o, shape_ch) |
function |
Builds an OrderedDict mapping each VRChat name (vrc.v_*) to a list of (shape_key, weight) pairs computed from the three source shape keys |
build_viseme_map weights
| VRChat Viseme |
Contributions |
vrc.v_aa |
A × 0.9998 |
vrc.v_ch |
CH × 0.9996 |
vrc.v_dd |
A × 0.3 + CH × 0.7 |
vrc.v_e |
A × 0.5 + CH × 0.2 |
vrc.v_ff |
A × 0.2 + CH × 0.4 |
vrc.v_ih |
CH × 0.7 + O × 0.3 |
vrc.v_kk |
A × 0.7 + CH × 0.4 |
vrc.v_nn |
A × 0.2 + CH × 0.7 |
vrc.v_oh |
A × 0.2 + O × 0.8 |
vrc.v_ou |
O × 0.9994 |
vrc.v_pp |
A × 0.0004 + O × 0.0004 |
vrc.v_rr |
CH × 0.5 + O × 0.3 |
vrc.v_sil |
A × 0.0002 + CH × 0.0002 |
vrc.v_ss |
CH × 0.8 |
vrc.v_th |
A × 0.4 + O × 0.15 |
utilities/helpers.py
| Name |
Type |
Description |
_PreviewState |
class |
Holds active (bool) and saved_values (dict) representing the current preview state |
_ps |
_PreviewState |
Global instance shared across all modules |
guess_shape(mesh_obj, candidates) |
function |
Iterates over candidates and returns the first name found among the mesh's shape keys, or '' |
_save_shapekey_values(mesh_obj) |
function |
Saves the current values of all shape keys into _ps.saved_values |
_restore_shapekey_values(mesh_obj) |
function |
Restores shape key values from _ps.saved_values |
_reset_all_shapekeys(mesh_obj) |
function |
Sets the value of every shape key on the mesh to 0.0 |
_apply_mix(mesh_obj, mix, intensity) |
function |
Resets all shape keys then applies the mix list of (name, weight) pairs scaled by intensity |
operators/vrc.py
Operators for VRChat viseme generation.
| Class |
bl_idname |
Description |
VRCVIS_OT_AutoDetect |
vrc_viseme.auto_detect |
Searches for common MMD shape key names and fills in the A/O/CH/Blink fields |
VRCVIS_OT_Preview |
vrc_viseme.preview |
Toggles a live viewport preview of the selected viseme |
VRCVIS_OT_UpdatePreview |
vrc_viseme.update_preview |
Refreshes the preview when the selected viseme or intensity changes |
VRCVIS_OT_Generate |
vrc_viseme.generate |
Generates the 15 vrc.v_* shape keys plus vrc.blink by mixing the three source shape keys |
VRCVIS_OT_RemoveAll |
vrc_viseme.remove_all |
Deletes all shape keys whose name starts with vrc. |
VRCVIS_OT_Reorder |
vrc_viseme.reorder |
Reorders vrc.* shape keys according to VRC_ORDER, placing them immediately after Basis |
operators/mmd.py
Operators for EN/VRChat → Japanese MMD conversion.
| Class |
bl_idname |
Description |
VRCVIS_OT_MMDAutoDetect |
vrc_viseme.mmd_auto_detect |
Automatically detects English/VRChat names and fills in the MMD fields |
VRCVIS_OT_MMDConvert |
vrc_viseme.mmd_convert |
Duplicates shape keys with Japanese MMD names and inserts the separators |
VRCVIS_OT_MMDRemove |
vrc_viseme.mmd_remove |
Removes all Japanese MMD shape keys and separators |
panels/main_panel.py
| Name |
Type |
Description |
viseme_enum_items(self, context) |
function |
Callback for the preview EnumProperty; returns all VRChat visemes plus vrc.blink |
VRCVIS_PT_Panel |
bpy.types.Panel |
Main panel in the Blender Sidebar; bl_idname = VIEW3D_PT_visemes_converter |
Scene Properties (bpy.types.Scene)
All properties are registered by register() in visemes.py with the vrcvis_ prefix.
| Property |
Type |
Description |
vrcvis_mesh |
StringProperty |
Name of the target mesh |
vrcvis_mouth_a |
StringProperty |
Open-mouth shape key (あ / A) |
vrcvis_mouth_o |
StringProperty |
Round-mouth shape key (お / O) |
vrcvis_mouth_ch |
StringProperty |
Narrow-mouth shape key (い / CH) |
vrcvis_blink |
StringProperty |
Eyes-closed shape key (まばたき / Blink) |
vrcvis_intensity |
FloatProperty |
Global weight multiplier (0.0 – 2.0, default 1.0) |
vrcvis_overwrite |
BoolProperty |
If True, regenerates already-existing shape keys |
vrcvis_preview_active |
BoolProperty |
Internal preview state (True = preview on) |
vrcvis_preview_viseme |
EnumProperty |
Viseme selected for preview |
vrcvis_mmd_{suffix} |
StringProperty |
One property per entry in MMD_JP_MAPPING (suffix from column 2) |
Typical Workflow
