MediaPlane/docs/User_Adjustable_Playback_Rate_Spec.md

User-Adjustable Playback Rate Specification

Overview

This document specifies the implementation details for allowing users to adjust video playback speed independently of Maya's timeline frame rate.

Requirements

• Provide a user-controllable playback rate multiplier attribute
• Allow playback rates from slow motion (0.1x) to fast motion (10.0x)
• Support reverse playback (negative rates) - optional
• Integrate with frame rate synchronization logic
• Maintain audio-video sync if audio is ever added (for future expansion)
• Provide smooth acceleration/deceleration when rate changes

Implementation Details

Attribute Definition

• playbackRate (double): User-adjustable playback rate multiplier
  • Default value: 1.0 (normal speed)
  • Minimum value: 0.01 (1% speed)
  • Maximum value: 10.0 (10x speed)
  • Keyable: Yes (can be animated)
  • Storable: Yes (saved with scene)
  • Readable/Writable: Yes

Integration with Frame Rate Synchronization

The playback rate multiplies the effective frame rate in the synchronization logic:

When useMayaFrameRate is true:

effectiveFrameRate = mayaFrameRate * playbackRate

When useMayaFrameRate is false:

effectiveFrameRate = videoFrameRate * playbackRate

Implementation Components

UI Considerations

• The attribute should appear in the node's attribute editor
• Consider adding a slider widget for intuitive control (via MPxNodeUI or similar)
• Provide visual feedback when rate is not 1.0

Behavior

• When playbackRate changes, recalculate target frame immediately
• Maintain synchronization with Maya's timeline when useMayaFrameRate is true
• Allow creative effects like slow motion, fast motion, and reverse playback
• Handle rate changes smoothly to avoid jumps in playback

Error Handling

• Clamp playbackRate to valid range in node compute method
• Handle extreme values gracefully
• Provide warnings in script editor for clamped values

Performance Considerations

• Simple multiplication operation, minimal performance impact
• No additional memory allocation required
• Attribute change notifications are lightweight

Integration Points

• MPxNode: Contains the playbackRate attribute
• Frame Rate Synchronization: Uses playbackRate in calculations
• Developer 2: Implements the attribute and integrates with synchronization logic

Maya API Specifics

• Use MFnNumericAttribute to create the attribute
• Set attribute properties (min, max, default, keyable, etc.)
• Handle attribute changes in compute method
• Use MFnDoubleData if storing as internal data (not needed for simple double attribute)

Dependencies

• MPxNode implementation
• Frame rate synchronization logic

Overview

This document specifies the implementation details for allowing users to adjust video playback speed independently of Maya's timeline frame rate.

Requirements

• Provide a user-controllable playback rate multiplier attribute
• Allow playback rates from slow motion (0.1x) to fast motion (10.0x)
• Support reverse playback (negative rates) - optional
• Integrate with frame rate synchronization logic
• Maintain audio-video sync if audio is ever added (for future expansion)
• Provide smooth acceleration/deceleration when rate changes

Implementation Details

Attribute Definition

• playbackRate (double): User-adjustable playback rate multiplier
  • Default value: 1.0 (normal speed)
  • Minimum value: 0.01 (1% speed)
  • Maximum value: 10.0 (10x speed)
  • Keyable: Yes (can be animated)
  • Storable: Yes (saved with scene)
  • Readable/Writable: Yes

Integration with Frame Rate Synchronization

The playback rate multiplies the effective frame rate in the synchronization logic:

When useMayaFrameRate is true:

effectiveFrameRate = mayaFrameRate * playbackRate

When useMayaFrameRate is false:

effectiveFrameRate = videoFrameRate * playbackRate

Implementation Components

UI Considerations

• The attribute should appear in the node's attribute editor
• Consider adding a slider widget for intuitive control (via MPxNodeUI or similar)
• Provide visual feedback when rate is not 1.0

Behavior

• When playbackRate changes, recalculate target frame immediately
• Maintain synchronization with Maya's timeline when useMayaFrameRate is true
• Allow creative effects like slow motion, fast motion, and reverse playback
• Handle rate changes smoothly to avoid jumps in playback

Error Handling

• Clamp playbackRate to valid range in node compute method
• Handle extreme values gracefully
• Provide warnings in script editor for clamped values

Performance Considerations

• Simple multiplication operation, minimal performance impact
• No additional memory allocation required
• Attribute change notifications are lightweight

Integration Points

• MPxNode: Contains the playbackRate attribute
• Frame Rate Synchronization: Uses playbackRate in calculations
• Developer 2: Implements the attribute and integrates with synchronization logic

Maya API Specifics

• Use MFnNumericAttribute to create the attribute
• Set attribute properties (min, max, default, keyable, etc.)
• Handle attribute changes in compute method
• Use MFnDoubleData if storing as internal data (not needed for simple double attribute)

Dependencies

• MPxNode implementation
• Frame rate synchronization logic