vstml-parser 0.1.0

package/README.md

@@ -0,0 +1,215 @@
+# vstml-parser
+
+> Official parser for **VSTML** — Video Speech Text Markup Language
+
+VSTML is an open markup language for AI-powered video editing. It gives AI a structured language to read, write, and edit video using timestamps from Whisper STT and metadata from FFmpeg — without requiring any vision model or ML training.
+
+```
+npm install vstml-parser
+```
+
+---
+
+## What is VSTML?
+
+VSTML is to video editing what HTML is to web pages. It describes a video's structure, speech, and edit operations in a format that both humans and AI can read and write.
+
+```
+[vstml version="0.1" mode="edit"]
+  [timeline duration="45s" fps="30"]
+    [scene id="s1" start="0s" end="14s"]
+      [clip id="c1" src="intro.mp4"]
+      [delete clip="c1" from="3.1s" to="4.9s"]
+      [delete clip="c1" from="5.9s" to="6.3s"]
+      [caption at="0.8s" duration="7s"]Hey everyone welcome back[/caption]
+    [/scene]
+    [transition type="crossdissolve" duration="0.5s" between="c1,c2"]
+  [/timeline]
+[/vstml]
+```
+
+---
+
+## Quick Start
+
+```javascript
+const {
+  parse,
+  parseAndValidate,
+  stringify,
+  query,
+  getTranscript,
+  getEditOperations
+} = require('vstml-parser')
+
+// Parse a VSTML string into an AST
+const ast = parse(vstmlString)
+
+// Parse and validate in one step
+const { ast, valid, errors, warnings } = parseAndValidate(vstmlString)
+
+// Find all nodes of a specific tag
+const scenes = query(ast, 'scene')
+const cuts = query(ast, 'cut')
+const silences = query(ast, 'silence')
+
+// Extract the full transcript from word-level timestamps
+const { text, words } = getTranscript(ast)
+
+// Get all edit operations sorted by timestamp
+const ops = getEditOperations(ast)
+
+// Convert AST back to VSTML text
+const output = stringify(ast)
+```
+
+---
+
+## API
+
+### `parse(input)`
+Parses a VSTML string and returns an AST.
+
+```javascript
+const ast = parse('[cut clip="c1" at="4.2s"]')
+// Returns: { nodeType: 'document', children: [...] }
+```
+
+### `parseAndValidate(input)`
+Parses and validates a VSTML string against the v0.1 spec.
+
+```javascript
+const { ast, valid, errors, warnings } = parseAndValidate(input)
+if (!valid) {
+  console.error(errors)
+}
+```
+
+### `stringify(ast)`
+Converts an AST back into formatted VSTML text.
+
+```javascript
+const vstmlText = stringify(ast)
+```
+
+### `query(ast, tagName)`
+Find all elements matching a tag name anywhere in the document.
+
+```javascript
+const words = query(ast, 'word')
+const effects = query(ast, 'effect')
+```
+
+### `getTranscript(ast)`
+Extract the full spoken transcript from `[word]` tags.
+
+```javascript
+const { text, words } = getTranscript(ast)
+// text: "Hey everyone welcome back"
+// words: [{ word: "Hey", timestamp: "0.5s", seconds: 0.5 }, ...]
+```
+
+### `getEditOperations(ast)`
+Get all edit operations (cut, trim, delete, etc.) sorted by timestamp.
+
+```javascript
+const ops = getEditOperations(ast)
+// [{ operation: "trim", attributes: {...}, timestamp: "0s", seconds: 0 }, ...]
+```
+
+---
+
+## AST Structure
+
+Every node has a `nodeType`:
+
+```javascript
+// Element node
+{
+  nodeType: 'element',
+  tag: 'scene',
+  attributes: { id: 's1', start: '0s', end: '14s' },
+  children: [...]
+}
+
+// Text node
+{
+  nodeType: 'text',
+  value: 'Hello World'
+}
+
+// Document root
+{
+  nodeType: 'document',
+  children: [...]
+}
+```
+
+---
+
+## VSTML Modes
+
+VSTML files operate in two modes:
+
+**`analysis`** — output of the Whisper STT + FFmpeg scraper pipeline. Describes what is in a video.
+
+**`edit`** — output of the AI editor. Describes what changes to make.
+
+```
+[vstml version="0.1" mode="analysis"]  ← describes the video
+[vstml version="0.1" mode="edit"]      ← describes the edits
+```
+
+---
+
+## Validation
+
+The validator checks:
+- Required attributes per tag
+- Timestamp format (must be like `"4.2s"` or `"10s"`)
+- Valid mode values (`"analysis"` or `"edit"`)
+- Known effect and transition types
+- Speed value format (`"1.5x"`)
+- maxpass must be a number
+
+```javascript
+const { valid, errors, warnings } = parseAndValidate(input)
+```
+
+---
+
+## Running Tests
+
+```bash
+npm test
+```
+
+---
+
+## VSTML Spec
+
+Full tag reference and specification:
+👉 [VSTML v0.1 Specification](https://github.com/YOUR_USERNAME/vstml-parser/blob/main/VSTML_SPEC_v0.1.md)
+
+---
+
+## Why VSTML?
+
+| Feature | VSTML | EDL | FCPXML |
+|---------|-------|-----|--------|
+| AI-readable | ✅ | ❌ | ❌ |
+| Human-readable | ✅ | Partial | ❌ |
+| Speech timestamps | ✅ | ❌ | ❌ |
+| Recursive AI loop | ✅ | ❌ | ❌ |
+| App independent | ✅ | Partial | ❌ |
+| No ML required | ✅ | ✅ | ✅ |
+
+---
+
+## License
+
+MIT — free to use, implement, and build on.
+
+---
+
+*VSTML is an open specification. Anyone may implement a VSTML parser or editor.*

package/index.js

@@ -0,0 +1,187 @@
+/**
+ * vstml-parser
+ * Official parser for VSTML — Video Speech Text Markup Language
+ *
+ * VSTML is an open markup language for AI-powered video editing.
+ * It gives AI a structured language to read, write, and edit video
+ * using timestamps from Whisper STT and metadata from FFmpeg —
+ * without requiring any vision model or ML training.
+ *
+ * @version 0.1.0
+ * @license MIT
+ */
+
+const { Lexer } = require('./src/lexer')
+const { Parser } = require('./src/parser')
+const { validate } = require('./src/validator')
+const { serialize } = require('./src/serializer')
+
+/**
+ * Parse a VSTML string into an AST
+ * @param {string} input - Raw VSTML text
+ * @returns {object} AST document node
+ *
+ * @example
+ * const { parse } = require('vstml-parser')
+ * const ast = parse('[scene id="s1" start="0s" end="10s"][/scene]')
+ */
+function parse(input) {
+  if (typeof input !== 'string') {
+    throw new TypeError('vstml-parser: input must be a string')
+  }
+  const lexer = new Lexer(input)
+  const tokens = lexer.tokenize()
+  const parser = new Parser(tokens)
+  return parser.parse()
+}
+
+/**
+ * Parse and validate a VSTML string
+ * @param {string} input - Raw VSTML text
+ * @returns {{ ast: object, valid: boolean, errors: string[], warnings: string[] }}
+ *
+ * @example
+ * const { parseAndValidate } = require('vstml-parser')
+ * const result = parseAndValidate(vstmlString)
+ * if (!result.valid) console.error(result.errors)
+ */
+function parseAndValidate(input) {
+  const ast = parse(input)
+  const { valid, errors, warnings } = validate(ast)
+  return { ast, valid, errors, warnings }
+}
+
+/**
+ * Convert a VSTML AST back into a formatted VSTML string
+ * @param {object} ast - AST produced by parse()
+ * @returns {string} Formatted VSTML text
+ *
+ * @example
+ * const { parse, stringify } = require('vstml-parser')
+ * const ast = parse(input)
+ * const output = stringify(ast)
+ */
+function stringify(ast) {
+  return serialize(ast)
+}
+
+/**
+ * Query the AST for all elements matching a tag name
+ * @param {object} ast - AST produced by parse()
+ * @param {string} tagName - Tag to search for e.g. "cut", "scene", "word"
+ * @returns {object[]} Array of matching AST nodes
+ *
+ * @example
+ * const cuts = query(ast, 'cut')
+ * const silences = query(ast, 'silence')
+ */
+function query(ast, tagName) {
+  const results = []
+
+  function walk(node) {
+    if (!node) return
+    if (node.nodeType === 'element' && node.tag === tagName) {
+      results.push(node)
+    }
+    for (const child of node.children || []) {
+      walk(child)
+    }
+  }
+
+  walk(ast)
+  return results
+}
+
+/**
+ * Get all timestamps from a VSTML document
+ * Useful for building a timeline view or verifying timing
+ * @param {object} ast - AST produced by parse()
+ * @returns {object[]} Array of { tag, timestamp, attributes }
+ */
+function getTimestamps(ast) {
+  const results = []
+  const TS_ATTRS = ['start', 'end', 'at', 'from', 'to']
+
+  function walk(node) {
+    if (!node) return
+    if (node.nodeType === 'element') {
+      for (const attr of TS_ATTRS) {
+        if (node.attributes && node.attributes[attr]) {
+          results.push({
+            tag: node.tag,
+            attribute: attr,
+            timestamp: node.attributes[attr],
+            seconds: parseFloat(node.attributes[attr]),
+            attributes: node.attributes,
+          })
+        }
+      }
+    }
+    for (const child of node.children || []) {
+      walk(child)
+    }
+  }
+
+  walk(ast)
+  return results.sort((a, b) => a.seconds - b.seconds)
+}
+
+/**
+ * Extract the full transcript from a VSTML analysis document
+ * Built from [word] tags with their timestamps
+ * @param {object} ast - AST produced by parse()
+ * @returns {{ text: string, words: object[] }}
+ */
+function getTranscript(ast) {
+  const words = query(ast, 'word').map(node => ({
+    word: node.children.find(c => c.nodeType === 'text')?.value || '',
+    timestamp: node.attributes?.t,
+    seconds: parseFloat(node.attributes?.t),
+  }))
+
+  return {
+    text: words.map(w => w.word).join(' '),
+    words,
+  }
+}
+
+/**
+ * Get all edit operations from an edit-mode VSTML document
+ * Returns cuts, deletes, trims, etc. sorted by timestamp
+ * @param {object} ast - AST produced by parse()
+ * @returns {object[]} Sorted array of edit operation nodes
+ */
+function getEditOperations(ast) {
+  const EDIT_TAGS = ['cut', 'trim', 'delete', 'split', 'merge', 'speed', 'reverse', 'reorder']
+  const ops = []
+
+  for (const tag of EDIT_TAGS) {
+    const nodes = query(ast, tag)
+    for (const node of nodes) {
+      const ts = node.attributes?.at || node.attributes?.from || node.attributes?.start || '0s'
+      ops.push({
+        operation: tag,
+        attributes: node.attributes,
+        timestamp: ts,
+        seconds: parseFloat(ts),
+      })
+    }
+  }
+
+  return ops.sort((a, b) => a.seconds - b.seconds)
+}
+
+module.exports = {
+  parse,
+  parseAndValidate,
+  stringify,
+  query,
+  getTimestamps,
+  getTranscript,
+  getEditOperations,
+  // Also export internals for advanced use
+  Lexer,
+  Parser,
+  validate,
+  serialize,
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "vstml-parser",
+  "version": "0.1.0",
+  "description": "Official parser for VSTML — Video Speech Text Markup Language. A structured markup language for AI-powered video editing.",
+  "keywords": [
+    "vstml",
+    "video",
+    "markup",
+    "language",
+    "parser",
+    "ai",
+    "editing",
+    "speech",
+    "whisper",
+    "ffmpeg",
+    "timeline"
+  ],
+  "homepage": "https://github.com/ADIBOYZ32/vstml-parser#readme",
+  "bugs": {
+    "url": "https://github.com/ADIBOYZ32/vstml-parser/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ADIBOYZ32/vstml-parser.git"
+  },
+  "license": "MIT",
+  "author": "ADIBOYZ32",
+  "type": "commonjs",
+  "main": "index.js",
+  "directories": {
+    "test": "test"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/parser.test.js"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/src/lexer.js

@@ -0,0 +1,113 @@
+/**
+ * VSTML Lexer
+ * Converts raw VSTML text into a flat list of tokens
+ */
+
+const TOKEN_TYPES = {
+  TAG_OPEN_START: 'TAG_OPEN_START',       // [tagname
+  TAG_CLOSE_START: 'TAG_CLOSE_START',     // [/tagname
+  TAG_END: 'TAG_END',                     // ]
+  ATTR_KEY: 'ATTR_KEY',                   // key
+  ATTR_VALUE: 'ATTR_VALUE',              // "value"
+  TEXT: 'TEXT',                           // text content between tags
+  EOF: 'EOF',
+}
+
+class Lexer {
+  constructor(input) {
+    this.input = input
+    this.pos = 0
+    this.tokens = []
+  }
+
+  peek() {
+    return this.input[this.pos] || null
+  }
+
+  consume() {
+    return this.input[this.pos++] || null
+  }
+
+  skipWhitespace() {
+    while (this.pos < this.input.length && /\s/.test(this.input[this.pos])) {
+      this.pos++
+    }
+  }
+
+  readUntil(chars) {
+    let result = ''
+    while (this.pos < this.input.length && !chars.includes(this.input[this.pos])) {
+      result += this.consume()
+    }
+    return result
+  }
+
+  readString() {
+    this.consume() // opening quote
+    let result = ''
+    while (this.pos < this.input.length && this.input[this.pos] !== '"') {
+      result += this.consume()
+    }
+    this.consume() // closing quote
+    return result
+  }
+
+  tokenize() {
+    while (this.pos < this.input.length) {
+      this.skipWhitespace()
+      if (this.pos >= this.input.length) break
+
+      const ch = this.peek()
+
+      if (ch === '[') {
+        this.consume() // [
+        const isClosing = this.peek() === '/'
+        if (isClosing) this.consume() // /
+
+        const tagName = this.readUntil([' ', ']', '\n', '\r', '\t']).trim()
+
+        if (isClosing) {
+          this.tokens.push({ type: TOKEN_TYPES.TAG_CLOSE_START, value: tagName })
+        } else {
+          this.tokens.push({ type: TOKEN_TYPES.TAG_OPEN_START, value: tagName })
+        }
+
+        // Parse attributes inside the tag
+        while (this.pos < this.input.length && this.peek() !== ']') {
+          this.skipWhitespace()
+          if (this.peek() === ']') break
+
+          // Read attribute key
+          const key = this.readUntil(['=', ']', ' ']).trim()
+          if (!key) { this.consume(); continue }
+
+          if (this.peek() === '=') {
+            this.consume() // =
+            if (this.peek() === '"') {
+              const value = this.readString()
+              this.tokens.push({ type: TOKEN_TYPES.ATTR_KEY, value: key })
+              this.tokens.push({ type: TOKEN_TYPES.ATTR_VALUE, value: value })
+            }
+          }
+        }
+
+        if (this.peek() === ']') {
+          this.consume() // ]
+          this.tokens.push({ type: TOKEN_TYPES.TAG_END, value: ']' })
+        }
+
+      } else {
+        // Text content
+        const text = this.readUntil(['[']).trim()
+        if (text) {
+          this.tokens.push({ type: TOKEN_TYPES.TEXT, value: text })
+        }
+      }
+    }
+
+    this.tokens.push({ type: TOKEN_TYPES.EOF, value: null })
+    return this.tokens
+  }
+}
+
+module.exports = { Lexer, TOKEN_TYPES }

package/src/parser.js

@@ -0,0 +1,149 @@
+/**
+ * VSTML Parser
+ * Converts a flat token list into a structured AST (Abstract Syntax Tree)
+ */
+
+const { Lexer, TOKEN_TYPES } = require('./lexer')
+
+// Set of tags that are always self-closing (never have children)
+const SELF_CLOSING_TAGS = new Set([
+  'cut', 'trim', 'delete', 'split', 'merge', 'speed', 'reverse', 'reorder',
+  'clip', 'audio', 'image', 'marker', 'silence', 'filler', 'audiospike',
+  'voiceover', 'subtitle', 'transition', 'effect', 'overlay', 'broll', 'pip',
+  'correction', 'approved', 'maxpass',
+])
+
+class Parser {
+  constructor(tokens) {
+    this.tokens = tokens
+    this.pos = 0
+  }
+
+  peek() {
+    return this.tokens[this.pos] || { type: TOKEN_TYPES.EOF, value: null }
+  }
+
+  consume() {
+    return this.tokens[this.pos++] || { type: TOKEN_TYPES.EOF, value: null }
+  }
+
+  // Collect attributes from the token stream until TAG_END
+  collectAttributes() {
+    const attrs = {}
+    while (
+      this.peek().type !== TOKEN_TYPES.TAG_END &&
+      this.peek().type !== TOKEN_TYPES.EOF
+    ) {
+      if (this.peek().type === TOKEN_TYPES.ATTR_KEY) {
+        const key = this.consume().value
+        if (this.peek().type === TOKEN_TYPES.ATTR_VALUE) {
+          attrs[key] = this.consume().value
+        }
+      } else {
+        this.consume()
+      }
+    }
+    if (this.peek().type === TOKEN_TYPES.TAG_END) {
+      this.consume() // consume ]
+    }
+    return attrs
+  }
+
+  // Parse a single node (tag or text)
+  parseNode() {
+    const token = this.peek()
+
+    if (token.type === TOKEN_TYPES.EOF) return null
+
+    // Closing tag — signal to parent to stop
+    if (token.type === TOKEN_TYPES.TAG_CLOSE_START) return null
+
+    // Text node
+    if (token.type === TOKEN_TYPES.TEXT) {
+      this.consume()
+      return { nodeType: 'text', value: token.value }
+    }
+
+    // Opening tag
+    if (token.type === TOKEN_TYPES.TAG_OPEN_START) {
+      this.consume() // consume tag name token
+      const tagName = token.value
+      const attributes = this.collectAttributes()
+
+      const node = {
+        nodeType: 'element',
+        tag: tagName,
+        attributes,
+        children: [],
+      }
+
+      // Self-closing tags never consume children
+      if (SELF_CLOSING_TAGS.has(tagName)) {
+        return node
+      }
+
+      // Parse children until we hit the matching closing tag
+      while (this.pos < this.tokens.length) {
+        const next = this.peek()
+
+        if (next.type === TOKEN_TYPES.EOF) break
+
+        // Check for matching closing tag
+        if (
+          next.type === TOKEN_TYPES.TAG_CLOSE_START &&
+          next.value === tagName
+        ) {
+          this.consume() // consume closing tag name
+          // consume TAG_END for closing tag
+          if (this.peek().type === TOKEN_TYPES.TAG_END) this.consume()
+          break
+        }
+
+        // Non-matching closing tag means we're done with this node's children
+        if (next.type === TOKEN_TYPES.TAG_CLOSE_START) break
+
+        // Skip stray TAG_END tokens inside children
+        if (next.type === TOKEN_TYPES.TAG_END) {
+          this.consume()
+          continue
+        }
+
+        const child = this.parseNode()
+        if (child) node.children.push(child)
+        else break
+      }
+
+      return node
+    }
+
+    // Skip unknown tokens
+    this.consume()
+    return null
+  }
+
+  // Parse the full document
+  parse() {
+    const root = {
+      nodeType: 'document',
+      children: [],
+    }
+
+    while (this.peek().type !== TOKEN_TYPES.EOF) {
+      // Skip stray TAG_END tokens at document level
+      if (this.peek().type === TOKEN_TYPES.TAG_END) {
+        this.consume()
+        continue
+      }
+      const node = this.parseNode()
+      if (node) root.children.push(node)
+      else if (this.peek().type !== TOKEN_TYPES.EOF) {
+        // Consume to avoid infinite loop on unrecognized tokens
+        this.consume()
+      }
+    }
+
+    return root
+  }
+}
+
+module.exports = { Parser }

package/src/serializer.js

@@ -0,0 +1,54 @@
+/**
+ * VSTML Serializer
+ * Converts a VSTML AST back into formatted VSTML text
+ * Useful for AI that generates AST objects and needs to output .vstml files
+ */
+
+function serializeNode(node, indent = 0) {
+  const pad = '  '.repeat(indent)
+
+  if (node.nodeType === 'text') {
+    return `${pad}${node.value}`
+  }
+
+  if (node.nodeType === 'element') {
+    const attrs = Object.entries(node.attributes || {})
+      .map(([k, v]) => `${k}="${v}"`)
+      .join(' ')
+
+    const attrStr = attrs ? ` ${attrs}` : ''
+    const openTag = `${pad}[${node.tag}${attrStr}]`
+
+    if (!node.children || node.children.length === 0) {
+      return openTag
+    }
+
+    // Check if all children are text nodes (inline)
+    const allText = node.children.every(c => c.nodeType === 'text')
+    if (allText) {
+      const text = node.children.map(c => c.value).join(' ')
+      return `${openTag}${text}[/${node.tag}]`
+    }
+
+    // Block children
+    const childLines = node.children
+      .map(child => serializeNode(child, indent + 1))
+      .join('\n')
+
+    return `${openTag}\n${childLines}\n${pad}[/${node.tag}]`
+  }
+
+  if (node.nodeType === 'document') {
+    return node.children
+      .map(child => serializeNode(child, indent))
+      .join('\n')
+  }
+
+  return ''
+}
+
+function serialize(ast) {
+  return serializeNode(ast)
+}
+
+module.exports = { serialize }

package/src/validator.js

@@ -0,0 +1,141 @@
+/**
+ * VSTML Validator
+ * Validates a parsed VSTML AST against the spec rules
+ * Returns a list of errors and warnings
+ */
+
+const VALID_TAGS = new Set([
+  // Document
+  'vstml', 'timeline',
+  // Media
+  'clip', 'audio', 'image',
+  // Structure
+  'scene', 'chapter', 'marker',
+  // Speech
+  'speech', 'word', 'silence', 'filler', 'audiospike', 'voiceover',
+  // Edit operations
+  'cut', 'trim', 'delete', 'split', 'merge', 'speed', 'reverse', 'reorder',
+  // Text
+  'text', 'caption', 'title', 'subtitle',
+  // Transitions
+  'transition',
+  // Effects
+  'effect',
+  // Overlay
+  'overlay', 'broll', 'pip',
+  // Recursive loop
+  'review', 'issue', 'correction', 'approved', 'maxpass',
+])
+
+const REQUIRED_ATTRS = {
+  vstml:      ['version', 'mode'],
+  timeline:   ['duration', 'fps'],
+  clip:       ['id', 'src'],
+  audio:      ['id', 'src'],
+  scene:      ['id', 'start', 'end'],
+  speech:     ['start', 'end'],
+  word:       ['t'],
+  silence:    ['start', 'end'],
+  filler:     ['word', 't'],
+  audiospike: ['at'],
+  cut:        ['clip'],
+  trim:       ['clip', 'from', 'to'],
+  delete:     ['clip', 'from', 'to'],
+  split:      ['clip', 'at'],
+  text:       ['start', 'end'],
+  caption:    ['at', 'duration'],
+  transition: ['type'],
+  effect:     ['type'],
+  review:     ['pass', 'goal'],
+  issue:      ['at', 'type'],
+  correction: ['for_issue', 'action'],
+  approved:   ['pass'],
+  maxpass:    ['value'],
+}
+
+const TIMESTAMP_REGEX = /^\d+(\.\d+)?s$/
+
+function validateTimestamp(value, tag, attr) {
+  if (value && !TIMESTAMP_REGEX.test(value)) {
+    return `[${tag}] attribute "${attr}" value "${value}" is not a valid timestamp. Use format like "4.2s" or "10s".`
+  }
+  return null
+}
+
+function validateNode(node, errors, warnings, context = {}) {
+  if (node.nodeType !== 'element') return
+
+  const tag = node.tag
+  const attrs = node.attributes || {}
+
+  // Check tag is known
+  if (!VALID_TAGS.has(tag)) {
+    warnings.push(`Unknown tag "[${tag}]" — not in VSTML v0.1 spec. It will be ignored by parsers.`)
+  }
+
+  // Check required attributes
+  const required = REQUIRED_ATTRS[tag] || []
+  for (const req of required) {
+    if (!attrs[req]) {
+      errors.push(`[${tag}] is missing required attribute "${req}".`)
+    }
+  }
+
+  // Timestamp validation for common attributes
+  const tsAttrs = ['start', 'end', 'at', 'from', 'to', 'duration']
+  for (const tsAttr of tsAttrs) {
+    if (attrs[tsAttr]) {
+      const err = validateTimestamp(attrs[tsAttr], tag, tsAttr)
+      if (err) errors.push(err)
+    }
+  }
+
+  // Rule: vstml must have valid mode
+  if (tag === 'vstml' && attrs.mode && !['analysis', 'edit'].includes(attrs.mode)) {
+    errors.push(`[vstml] mode must be "analysis" or "edit", got "${attrs.mode}".`)
+  }
+
+  // Rule: effect must have known type
+  const EFFECT_TYPES = ['colorgrade', 'blur', 'zoom', 'brightness', 'contrast', 'saturation', 'eq', 'compression', 'normalize']
+  if (tag === 'effect' && attrs.type && !EFFECT_TYPES.includes(attrs.type)) {
+    warnings.push(`[effect] type "${attrs.type}" is not a standard VSTML effect type.`)
+  }
+
+  // Rule: transition must have known type
+  const TRANSITION_TYPES = ['cut', 'fade', 'crossdissolve', 'wipe', 'zoom', 'flash']
+  if (tag === 'transition' && attrs.type && !TRANSITION_TYPES.includes(attrs.type)) {
+    warnings.push(`[transition] type "${attrs.type}" is not a standard VSTML transition type.`)
+  }
+
+  // Rule: maxpass value should be a number
+  if (tag === 'maxpass' && attrs.value && isNaN(Number(attrs.value))) {
+    errors.push(`[maxpass] value must be a number, got "${attrs.value}".`)
+  }
+
+  // Rule: speed value format
+  if (tag === 'speed' && attrs.value && !/^\d+(\.\d+)?x$/.test(attrs.value)) {
+    errors.push(`[speed] value must be in format like "1.5x" or "0.5x", got "${attrs.value}".`)
+  }
+
+  // Recurse into children
+  for (const child of node.children || []) {
+    validateNode(child, errors, warnings, context)
+  }
+}
+
+function validate(ast) {
+  const errors = []
+  const warnings = []
+
+  for (const child of ast.children || []) {
+    validateNode(child, errors, warnings)
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}
+
+module.exports = { validate }