Accessing d3 Projects

To access d3 project files on your network, you’ll need to combine two pieces of information:

1. The machine name (hostname) from DNS-SD discovery
2. The project path from the Projects API endpoint

Working in Sessions

When working with d3 in a session (multiple machines), it’s important to note that project access should be directed to the session’s director machine. You can determine if you’re in a session and identify the director in two ways:

1. Using DNS-SD Discovery (Recommended)

d3 provides a specific DNS-SD service type for discovering the director:

_d3director._tcp.local.

This will give you the director’s hostname directly, which is the preferred method for finding the director in a session.

2. Using the Session Status API

Alternatively, you can query the session status endpoint:

curl http://localhost/api/session/status/session

If the response shows "isRunningSolo": false, you’re in a session and should use the director’s hostname for all project operations.

The director’s information will be included in the response:

{
    "result": {
        "isRunningSolo": false,
        "director": {
            "hostname": "director-machine-name",
            // ... other director details
        }
    }
}

When in a session, all subsequent project operations should be directed to the director’s hostname rather than any arbitrary d3 machine on the network.

DNS-SD Discovery

First, use DNS-SD (Bonjour) to discover d3 machines on your network. Each d3 machine advertises itself using the service type _d3api._tcp.local.. When you discover a service, you’ll get:

• The machine’s hostname (e.g. “MyD3Machine”)
• The IP address
• The port number for the d3 API

Projects API Endpoint

Once you have the machine’s address, you can query the Projects API endpoint:

GET http://{ip}:{port}/api/service/system/projects

This endpoint returns a list of projects on the machine, including their paths. The response will look something like:

{
  "status": {
    "code": 0,
    "message": "",
    "details": []
  },
  "result": [
    {
      "hostname": "MyD3Machine",
      "lastProject": "Shows/MyShow",
      "projects": [
        {
          "path": "Shows/MyShow",
          "lastModified": "2024-01-22T10:00:00Z",
          "version": {
            "major": 24,
            "minor": 0,
            "hotfix": 0,
            "revision": 0
          }
        }
      ]
    }
  ]
}

The response includes additional useful information:

• lastProject: The most recently opened project
• lastModified: When the project was last modified
• version: The d3 version that last saved the project

Combining the Information

With both pieces of information, you can construct the full UNC path to the project:

\\{machine_name}\d3 Projects\{project path}

For example:

\\MyD3Machine\d3 Projects\Shows\MyShow

Alternative Access via rsync

You can also use rsync to access and manage project files. The rsync URL format is:

rsync://{machine_name}/d3projects/{project_path}

For example:

rsync://MyD3Machine/d3projects/Shows/MyShow

Example rsync Commands

To copy files to a project:

# Copy a single file to the project's media folder
rsync -av myVideo.mov rsync://MyD3Machine/d3projects/Shows/MyShow/objects/videoFile/

# Sync an entire local folder with a project folder
rsync -avz --progress ./local-objects/ rsync://MyD3Machine/d3projects/Shows/MyShow/objects/

# Download project content to a local backup
rsync -avz --progress rsync://MyD3Machine/d3projects/Shows/MyShow/ ./project-backup/

Common rsync flags:

• -a: Archive mode (preserves permissions, timestamps, etc.)
• -v: Verbose output
• -z: Compress data during transfer
• --progress: Show progress during transfer

This method is particularly useful for:

• Efficiently copying files to/from projects
• Synchronizing project content across machines
• Automated backup workflows
• Cross-platform file operations

This path can be used to:

• Access project files directly
• Set up file watchers
• Import/export resources
• Backup project files

Best Practices

1. Always validate that the machine is accessible before attempting to access project files
2. Handle network connectivity issues gracefully
3. Consider implementing retry logic for API calls
4. Cache discovered machine information when appropriate
5. Respect file locks and multi-user editing scenarios

Putting it all together

Here’s a complete example in Python that demonstrates discovering a d3 machine, checking for sessions, finding a project, and copying a video file into it:

import zeroconf
import requests
import subprocess
import time

def get_session_status():
    """Check if we're in a session and get director information if we are."""
    response = requests.get('http://localhost/api/session/status/session')
    data = response.json()
    return data['result']

def get_target_machine():
    """Determine the target machine based on session status."""
    zc = zeroconf.Zeroconf()
    
    # First try to find the director using DNS-SD
    director_browser = zeroconf.ServiceBrowser(zc, "_d3director._tcp.local.")
    time.sleep(1)  # Give time for discovery
    
    if director_browser.services:
        # We found a director, use its hostname
        service_info = director_browser.services[0]
        return service_info.server.rstrip('.')
    
    # If no director found, check if we're in a session using the API
    session_status = get_session_status()
    if not session_status['isRunningSolo']:
        # We're in a session, use the director from the API
        return session_status['director']['hostname']
    else:
        # We're in solo mode, discover a d3 machine
        d3_browser = zeroconf.ServiceBrowser(zc, "_d3api._tcp.local.")
        time.sleep(1)  # Give time for discovery
        
        # Get the first d3 machine found
        service_info = d3_browser.services[0]
        return service_info.server.rstrip('.')

def main():
    # 1. Determine target machine based on session status
    machine_name = get_target_machine()
    
    # 2. Get projects list from the API
    projects_url = f"http://{machine_name}/api/service/system/projects"
    response = requests.get(projects_url)
    projects_data = response.json()
    
    # Find the first project (in practice, you might want to let the user choose)
    project = projects_data['result'][0]['projects'][0]
    project_path = project['path']
    
    # 3. Use rsync to copy a video file into the project's videoFile folder
    source_file = "my_video.mov"
    
    # Option 1: Using rsync (Linux/Mac/Windows with rsync installed)
    rsync_destination = f"rsync://{machine_name}/d3projects/{project_path}/objects/videoFile/"
    
    try:
        # Execute rsync command if available
        rsync_command = [
            "rsync",
            "-avz",
            "--progress",
            source_file,
            rsync_destination
        ]
        subprocess.run(rsync_command, check=True)
    except (subprocess.SubprocessError, FileNotFoundError):
        # Option 2: Fallback to network copy for Windows environments
        import shutil
        import os
        
        # Construct UNC path for Windows
        unc_path = f"\\\\{machine_name}\\d3 Projects\\{project_path}\\objects\\videoFile\\"
        target_path = os.path.join(unc_path, os.path.basename(source_file))
        
        # Copy using shutil
        shutil.copy2(source_file, target_path)
    
    print(f"Successfully copied {source_file} to {machine_name}'s project: {project_path}")

if __name__ == "__main__":
    main()

This script:

1. Checks if we’re in a session and determines the appropriate target machine
2. Uses the director’s hostname if in a session, otherwise discovers a d3 machine
3. Queries the Projects API to get available projects
4. Attempts to use rsync first, then falls back to Windows network copy if rsync is not available