optimize_cue_timing

Instructions

Implementation Reference

• src/tools/cue-tools.ts:361-405 (handler)

  Main handler function for optimize_cue_timing tool. Parses input schema, validates project and cue list, generates timing optimizations using helper method, computes statistics, and returns optimization results including changes and reasoning.

  async optimizeCueTiming(args: z.infer<typeof OptimizeCueTimingSchema>) {
    const { cueListId, projectId, optimizationStrategy } =
      OptimizeCueTimingSchema.parse(args);
  
    try {
      const project = await this.graphqlClient.getProject(projectId);
      if (!project) {
        throw new Error(`Project with ID ${projectId} not found`);
      }
  
      const cueList = project.cueLists.find((cl) => cl.id === cueListId);
      if (!cueList) {
        throw new Error(`Cue list with ID ${cueListId} not found`);
      }
  
      const optimizations = this.generateTimingOptimizations(
        cueList.cues,
        optimizationStrategy,
      );
  
      return {
        cueListId,
        strategy: optimizationStrategy,
        originalTiming: {
          totalCues: cueList.cues.length,
          averageFadeIn: this.calculateAverageFadeTime(
            cueList.cues,
            "fadeInTime",
          ),
          averageFadeOut: this.calculateAverageFadeTime(
            cueList.cues,
            "fadeOutTime",
          ),
          followCues: cueList.cues.filter((cue) => cue.followTime !== undefined)
            .length,
        },
        optimizedTiming: optimizations.newTiming,
        changes: optimizations.changes,
        reasoning: optimizations.reasoning,
        estimatedImprovement: optimizations.improvement,
      };
    } catch (error) {
      throw new Error(`Failed to optimize cue timing: ${error}`);
    }
  }

• src/tools/cue-tools.ts:46-57 (schema)

  Zod input schema validation for the optimize_cue_timing tool defining required cueListId, projectId, and optional optimizationStrategy.

  const OptimizeCueTimingSchema = z.object({
    cueListId: z.string(),
    projectId: z.string(),
    optimizationStrategy: z
      .enum([
        "smooth_transitions",
        "dramatic_timing",
        "technical_precision",
        "energy_conscious",
      ])
      .default("smooth_transitions"),
  });

• src/index.ts:1256-1282 (registration)

  Tool registration in ListToolsRequestSchema handler, defining name, description, and inputSchema matching the Zod schema.

  name: "optimize_cue_timing",
  description: "Optimize the timing of cues in a cue list",
  inputSchema: {
    type: "object",
    properties: {
      cueListId: {
        type: "string",
        description: "Cue list ID to optimize",
      },
      projectId: {
        type: "string",
        description: "Project ID containing the cue list",
      },
      optimizationStrategy: {
        type: "string",
        enum: [
          "smooth_transitions",
          "dramatic_timing",
          "technical_precision",
          "energy_conscious",
        ],
        default: "smooth_transitions",
        description: "Optimization strategy to apply",
      },
    },
    required: ["cueListId", "projectId"],
  },

• src/index.ts:2282-2294 (registration)

  Tool call handler registration in CallToolRequestSchema switch statement, dispatching to cueTools.optimizeCueTiming.

  case "optimize_cue_timing":
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            await this.cueTools.optimizeCueTiming(args as any),
            null,
            2,
          ),
        },
      ],
    };

• src/tools/cue-tools.ts:574-610 (helper)

  Private helper method implementing the core optimization logic based on strategy, generating changes, reasoning, and improvement metrics used by the handler.

  private generateTimingOptimizations(cues: any[], strategy: string) {
    // Simplified optimization logic - in practice this would be more sophisticated
    const changes = [];
    let improvement = "";
  
    switch (strategy) {
      case "smooth_transitions":
        changes.push("Standardized fade times for consistency");
        changes.push("Added buffer time between manual cues");
        improvement = "Smoother visual transitions";
        break;
      case "dramatic_timing":
        changes.push("Shortened fade times for dramatic moments");
        changes.push("Added follow cues for automatic sequences");
        improvement = "Enhanced dramatic impact";
        break;
      case "technical_precision":
        changes.push("Standardized cue numbering increments");
        changes.push("Consistent fade time patterns");
        improvement = "Easier operation and fewer mistakes";
        break;
      case "energy_conscious":
        changes.push("Longer fade times to reduce power spikes");
        changes.push("Staggered fixture activation");
        improvement = "Reduced power consumption peaks";
        break;
    }
  
    return {
      newTiming: {
        /* optimized timing values */
      },
      changes,
      reasoning: `Applied ${strategy} optimization strategy`,
      improvement,
    };
  }