feat: improve checking of audio clip times in Media Overlays

- Integrate code from the DAISY Consortium to parse and compare SMIL
  clock values
- Update check: move the clipBegin/clipEnd equality test into Java code
  so it works even with different SMIL clock syntaxes
- New check: clipBegin is not temporally after clipEnd
- Add and update associated tests

Author: mattgarrish

src/main/java/com/adobe/epubcheck/messages/DefaultSeverities.java

@@ -144,6 +144,8 @@ private void initialize()
     severities.put(MessageId.MED_005, Severity.ERROR);
     severities.put(MessageId.MED_006, Severity.USAGE);
     severities.put(MessageId.MED_007, Severity.ERROR);
+    severities.put(MessageId.MED_008, Severity.ERROR);
+    severities.put(MessageId.MED_009, Severity.ERROR);
 
     // NAV
     severities.put(MessageId.NAV_001, Severity.ERROR);

src/main/java/com/adobe/epubcheck/messages/MessageId.java

@@ -138,6 +138,8 @@ public enum MessageId implements Comparable<MessageId>
   MED_005("MED-005"),
   MED_006("MED_006"),
   MED_007("MED_007"),
+  MED_008("MED-008"),
+  MED_009("MED-009"),
 
   // Epub3 based table of content errors
   NAV_001("NAV-001"),

src/main/java/com/adobe/epubcheck/overlay/ClipTime.java

@@ -0,0 +1,53 @@
+/*
+ * This class was originally created by the DAISY Consortium
+ * for another project, licensed under LGPL v2.1.
+ * It is now integrated in EPUBCheck and relicensed under
+ * EPUBCheck’s primary license.
+ * See https://github.com/w3c/epubcheck/pull/1173
+ */
+package com.adobe.epubcheck.overlay;
+
+public class ClipTime {
+
+	private final Double timeInMs;
+
+	public ClipTime() {
+		timeInMs = null;
+	}
+	
+	public ClipTime(double timeInMs) {
+		this.timeInMs = new Double(timeInMs);
+	}
+
+	public double getTimeInMs() {
+		if(notSet()) {
+			return 0;
+		} else {
+			return timeInMs;
+		}
+	}
+
+	public ClipTime roundedToMilliSeconds() {
+		return new ClipTime(Math.round(this.getTimeInMs()));
+	}
+
+	public ClipTime floorToMilliSeconds() {
+		return new ClipTime(Math.floor(this.getTimeInMs()));
+	}
+
+	public boolean notSet() {
+		if(this.timeInMs == null) {
+			return true;
+		} else {
+			return false;
+		}
+	}
+
+	public ClipTime add(ClipTime timeToAdd) {
+		return new ClipTime(this.getTimeInMs() + timeToAdd.getTimeInMs());
+	}
+
+	public ClipTime subtract(ClipTime timeToSubtract) {
+		return new ClipTime(this.getTimeInMs() - timeToSubtract.getTimeInMs());
+	}
+}

src/main/java/com/adobe/epubcheck/overlay/OverlayHandler.java

@@ -39,7 +39,7 @@ public class OverlayHandler implements XMLHandler
   private boolean checkedUnsupportedXMLVersion;
 
   private Map<String, Vocab> vocabs = RESERVED_VOCABS;
-
+  
   public OverlayHandler(ValidationContext context, XMLParser parser)
   {
     this.context = context;
@@ -78,12 +78,48 @@ else if (name.equals("text"))
     else if (name.equals("audio"))
     {
       processRef(e.getAttribute("src"), XRefChecker.Type.AUDIO);
+      checkTime(e.getAttribute("clipBegin"), e.getAttribute("clipEnd"));
     }
     else if (name.equals("body") || name.equals("par"))
     {
       checkType(e.getAttributeNS(EpubConstants.EpubTypeNamespaceUri, "type"));
     }
   }
+  
+  private void checkTime(String clipBegin, String clipEnd) {
+  
+    if (clipEnd == null) {
+      // missing clipEnd attribute means clip plays to end so no comparisons possible
+      return;
+    }
+    
+    if (clipBegin == null) {
+      // set clipBegin to 0 if the attribute isn't set to allow comparisons
+      clipBegin = "0";
+    }
+    
+    SmilClock start;
+    SmilClock end;
+    
+    try {
+      start = new SmilClock(clipBegin);
+      end = new SmilClock(clipEnd);
+    }
+    catch (Exception ex) {
+      // invalid clock time will be reported by the schema
+      return;
+    }
+    
+    if (start.compareTo(end) == 1) {
+      // clipEnd is chronologically before clipBegin
+      report.message(MessageId.MED_008, EPUBLocation.create(path, parser.getLineNumber(), parser.getColumnNumber()));
+    }
+    
+    else if (start.equals(end)) {
+      // clipBegin and clipEnd are equal
+      report.message(MessageId.MED_009, EPUBLocation.create(path, parser.getLineNumber(), parser.getColumnNumber()));
+    }
+  }
 
   private void checkType(String type)
   {
@@ -149,5 +185,4 @@ public void ignorableWhitespace(char[] chars, int arg1, int arg2)
   public void processingInstruction(String arg0, String arg1)
   {
   }
-
 }