Skip to content
audioproxy

Rails

To play a variant of an uploaded file in a Rails view, you need a signed proxy URL for it. audioproxy-rails builds those URLs: hand it an ActiveStorage attachment (or a plain source string), describe the variant, and it resolves the blob’s storage service into the source form the proxy speaks, renders the options, and signs the result. It hooks in through a railtie; nothing to mount, no routes added.

# Gemfile
gem "audioproxy-rails"

Tell it where the proxy lives and how to sign, with the same key and salt the proxy boots with:

# bin/rails credentials:edit
audioproxy:
  endpoint: https://audio.example.com
  key: 7a3f9c21…      # hex, the proxy's AP_KEY
  salt: 9c217a3f…     # hex, the proxy's AP_SALT

If your deployment carries secrets in environment variables rather than Rails credentials, configure in an initializer instead:

config/initializers/audioproxy.rb
Audioproxy.configure do |config|
  config.endpoint = "https://audio.example.com"   # absolute http(s) URL, path prefix allowed
  config.key      = ENV["AP_KEY"]                 # hex string, decoded at assignment
  config.salt     = ENV["AP_SALT"]                # hex string, decoded at assignment
end

Then, to put a playable 96 kbps Opus version of an upload on a page (format: and bitrate: are the spelled-out aliases of the proxy’s f: and br: transforms):

<%= audioproxy_audio_tag @recording.audio,
      format: "opus", bitrate: 96,
      html: { controls: true } %>

@recording.audio is an ordinary has_one_attached. The helper reads which storage service the blob lives on (S3 and Disk are supported), builds the matching source string, and returns an <audio> tag whose src is the signed variant URL. Outside of views, or without ActiveStorage:

Audioproxy.url_for("s3://masters/2026/piece-final.wav",
                   format: "opus", bitrate: 96)

For development against a proxy running AP_ALLOW_INSECURE, set config.unsigned = true and skip the key entirely.

The gem’s README is canonical for the rest: the full option vocabulary and aliases, configuration precedence (credentials, ENV, initializer), the preload-hint helper, and the deployment coupling that Disk-service resolution brings.