Added beep(short, short) and beep(String) to the Machine interface. Closes #1112.

Allows architectures (and components or anything else for that matter) to play custom tones and beep patterns.

src/main/java/li/cil/oc/api/API.java

@@ -16,7 +16,7 @@ import li.cil.oc.api.detail.NetworkAPI;
  */
 public class API {
     public static final String ID_OWNER = "OpenComputers|Core";
-    public static final String VERSION = "5.2.2";
+    public static final String VERSION = "5.2.3";
 
     public static DriverAPI driver = null;
     public static FileSystemAPI fileSystem = null;

src/main/java/li/cil/oc/api/machine/Machine.java

@@ -141,6 +141,51 @@ public interface Machine extends ManagedEnvironment, Context {
      */
     double cpuTime();
 
+    // ----------------------------------------------------------------------- //
+
+    /**
+     * Play a sound using the machine's built-in speaker.
+     * <p/>
+     * This is what's used to emit beep codes when an error occurs while trying
+     * to start the computer, for example, and what's used for playing sounds
+     * when <tt>computer.beep</tt> is called.
+     * <p/>
+     * Be responsible in how you limit calls to this, as each call will cause
+     * a packet to be sent to all nearby clients, and will cause the receiving
+     * clients to generate the required sound sample on-the-fly. It is
+     * therefore recommended to not call this too frequently, and to limit the
+     * length of the sound to something relatively short (not longer than a few
+     * seconds at most).
+     * <p/>
+     * The audio will be played at the machine's host's location.
+     *
+     * @param frequency the frequency of the tone to generate.
+     * @param duration  the duration of the tone to generate, in milliseconds.
+     */
+    void beep(short frequency, short duration);
+
+    /**
+     * Utility method for playing beep codes.
+     * <p/>
+     * The underlying functionality is similar to that of {@link #beep(short, short)},
+     * except that this will play tones at a fixed frequency, and two different
+     * durations - in a pattern as defined in the passed string.
+     * <p/>
+     * This is useful for generating beep codes, such as for boot errors. It
+     * has the advantage of only generating a single network packet, and
+     * generating a single, longer sound sample for the full pattern. As such
+     * the same considerations should be made as for {@link #beep(short, short)},
+     * i.e. prefer not to use overly long patterns.
+     * <p/>
+     * The passed pattern must consist of dots (<tt>.</tt>) and dashes (<tt>-</tt>),
+     * where a dot is short tone, and a dash is a long tone.
+     * <p/>
+     * The audio will be played at the machine's host's location.
+     *
+     * @param pattern the beep pattern to play.
+     */
+    void beep(String pattern);
+
     /**
      * Crashes the computer.
      * <p/>
@@ -221,6 +266,8 @@ public interface Machine extends ManagedEnvironment, Context {
      */
     Object[] invoke(Value value, String method, Object[] args) throws Exception;
 
+    // ----------------------------------------------------------------------- //
+
     /**
      * The list of users registered on this machine.
      * <p/>

src/main/scala/li/cil/oc/server/machine/Machine.scala

@@ -235,10 +235,6 @@ class Machine(val host: MachineHost) extends prefab.ManagedEnvironment with mach
       false
   })
 
-  private def beep(pattern: String) {
-    PacketSender.sendSound(host.world, host.xPosition, host.yPosition, host.zPosition, pattern)
-  }
-
   override def pause(seconds: Double): Boolean = {
     val ticksToPause = math.max((seconds * 20).toInt, 0)
     def shouldPause(state: Machine.State.Value) = state match {
@@ -270,6 +266,14 @@ class Machine(val host: MachineHost) extends prefab.ManagedEnvironment with mach
       true
   })
 
+  override def beep(frequency: Short, duration: Short): Unit = {
+    PacketSender.sendSound(host.world, host.xPosition, host.yPosition, host.zPosition, frequency, duration)
+  }
+
+  override def beep(pattern: String) {
+    PacketSender.sendSound(host.world, host.xPosition, host.yPosition, host.zPosition, pattern)
+  }
+
   override def crash(message: String) = {
     this.message = Option(message)
     state.synchronized {