<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="./_c74_ref.xsl" type="text/xsl"?>
<c74object category="Live MSP Objects" module="m4l" name="live.remote~">
	<digest> Realtime control of parameters in Ableton Live and Max for Live. </digest>
	<description>
	 The
	<o>live.remote~</o>
	 object allows you to remotely control parameters in Ableton Live and Max for Live in realtime. 
	 To understand more about Live's parameters, look up the DeviceParameter Object Class in the
	 <link type="vignette" module="core" name="live_object_model">Live Object Model</link>
	 .
	</description>
	<discussion>
	A parameter in Live and Max for Live is selected using
	<o>live.path</o> or 
	<o>live.map</o>
	 and its id is sent to the right inlet of
	<o>live.remote~</o>
	 . An example path of a DeviceParameter is
	<m>live_set master_track mixer_device volume</m>
	 . Alternatively, you can get the path to a parameter in Ableton Live's interface by right-clicking a parameter and selecting "Copy LOM Path" in the context-menu (available only in Ableton Live 12).
	<br/>
	<br/>
	 Integer or float values are sent to the left inlet of
	<o>live.remote~</o>
	 , as messages or as an audio signal. The values are applied sample-accurately
	(if sent by the audio thread of Max) with a constant latency of a single
	audio buffer.
	<br/>
	<br/>
	 A parameter is disabled in Live while it is controlled by a
	<o>live.remote~</o>
	 , just as if it were controlled by a Macro parameter (but without the green
	dot). This means that any parameter automation is disabled and the
	value in the Live set is not changed. Additionally, no undo steps are created. The
	envelopes remain active. To stop remote-controlling a device parameter and to
	re-enable it, send
	<m>id 0</m>
	 to the right inlet of
	<o>live.remote~</o>
	 .
	</discussion>
	<!--METADATA-->
	<metadatalist>
		<metadata name="author"> Cycling '74, Ableton </metadata>
		<metadata name="tag"> Live </metadata>
	</metadatalist>
	<inletlist/>
	<outletlist/>
	<!--INLETS-->
	<apiinletlist>
		<inlet id="0" name="Left inlet">
			<digest>
		value (signal/float)
		</digest>
			<description>
		Sets the value of the parameter object specified by <m>id</m> in the right
		inlet. For the valid range, refer to the min and max properties of the
		target parameter. The value curve is linear to the parameter's GUI
		control in Live.
		</description>
		</inlet>
		<inlet id="1" name="Right inlet">
			<digest>
				<m>
			 id
			<i>nn</i>
		</m>
			</digest>
			<description>
		Sets object <m>id</m> in the format
		<m>
			 id
			<i>nn</i>
		</m>
		 to select the target parameter (DeviceParameter Object) in Live and Max for Live to control.
		<br/>
		<m>id 0</m>
		 means no object, i.e. the remote stops controlling the target parameter. This is also the initial state.
		</description>
		</inlet>
	</apiinletlist>
	<!--OUTLETS-->
	<!--ARGUMENTS-->
	<objarglist> </objarglist>
	<!--MESSAGES-->
	<methodlist>
		<method name="float">
			<arglist>
				<arg name="value" optional="0" type="float"/>
			</arglist>
			<digest>
		Send a decimal value to the selected Live Parameter
		</digest>
			<description>
		A floating point number value received in the left inlet will be
		applied to the selected Live parameter (DeviceParameter Object), if any, at the beginning of the next audio buffer, or at the end of a pending ramp (see <at>smoothing</at>).
		</description>
		</method>
		<method name="int">
			<arglist>
				<arg name="value" optional="0" type="int"/>
			</arglist>
			<digest>
		Send a value to the selected Live Parameter
		</digest>
			<description>
		An integer number value received in the left inlet will be applied to
		the selected Live parameter (DeviceParameter Object), if any, at the beginning of the next audio buffer, or at the end of a pending ramp (see <at>smoothing</at>).
		</description>
		</method>

		<method name="list">
			<arglist>
				<arg name='target-value' optional='0' type='float'/>
				<arg name='delta-time' optional='0' units='ms' type='number'/>
			</arglist>
			<digest>
				Start a ramp
			</digest>
			<description>
				Start a ramp with a list of two floats, similar to the <o>line~</o> object. Sending in “1 500” means that the value 1 will be reached in 500 ms, 
				starting at the current value. New ramps will always override the current ramp, so if you want to cut short a ramp, send another value.
			</description>
		</method>

		<method name="signal">
			<digest>
		Send signal values to the selected Live Parameter
		</digest>
			<description>
		Signal input values received in the left inlet will be applied to the
		selected parameter (DeviceParameter Object), if any, in realtime.

		</description>
		</method>
		<method name="id">
			<arglist>
				<arg name="parameter id" type="int" optional="0" />
			</arglist>
			<digest>
		Set the Live object using it's <m>id <i>nn</i></m>
		</digest>
			<description>
		In right inlet: Sets the selected object. The message has
		no effect if the id is not a parameter (DeviceParameter Object).

		</description>
		</method>
		<method name="getid">
			<arglist />
			<digest>
				Report the mapped object's id
			</digest>
			<description>
				The mapped object's id is sent from the outlet, preceded by the word <m>id</m>. If there is no mapped object, <m>id 0</m> will be sent.
			</description>
		</method>
	</methodlist>
	<!--ATTRIBUTES-->
	<attributelist>
		<attribute name="smoothing" get="1" set="1" type="float" size="1">
			<digest>
				Smoothing (ms) downsamples the input signal
			</digest>
			<description>
				Set the ramp time that is used for each incoming event. This also performs a temporal downsampling of any signal you send in. 
				For example, a smoothing value of 1 ms will sample the incoming signal every 1 ms and send ramp events which output a linear approximation of the signal. This attribute defaults to 1 ms.
			</description>
			<attributelist>
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Smoothing (ms)" />
				<attribute name="save" get="1" set="1" type="int" size="1" value="1" />
			</attributelist>
		</attribute>
		<attribute name="normalized" set="1" type="int" size="1">
			<digest>
				Automatically scale the input values to the parameter range
			</digest>
			<description>
				Toggles the
				<o>live.remote~</o>
				object's normalized mode, which automatically scales the input values to the target parameter range. When the normalized attribute is set to 1, 
				sending a signal or values in the range 0 to 1 to <o>live.remote~</o> will automatically scale the values to the range of the receiving parameter. 
				If the normalized attribute is set to 0, automatic scaling is disabled. You will need to provide values between the minimum and maximum of the parameter in order to control it.
			</description>
			<attributelist>
				<attribute name="label" set="1" type="symbol" size="1" value="Normalized" />
				<attribute name="save" set="1" type="int" size="1" value="1" />
			</attributelist>
		</attribute>
	</attributelist>
	<!--MISC-->
	<misc name="Inspector">
		<entry name="Persistence">
			<description>
		The
		<o>live.remote~</o>
		 object has a special entry in its inspector labeled "Use Persistent
		Mapping". This setting, when enabled, causes the
		<m>id</m>
		 associated with the object, in this case the id of the parameter, to persist when the Ableton Live Set is saved
		and restored, and when the Max Device is moved between the Live
		application and the Max editor, or within the Live Set. Beginning in
		Live 8.2.2, Live API ids remain persistent between launches of Live,
		which in conjunction with the
		<m>Persistence</m>
		 feature of
		<o>live.object</o>
		 ,
		<o>live.observer</o>
		 and
		<o>live.remote~</o>
		 , makes it possible to create simpler devices which retain their
		association with elements in the Ableton Live user interface.
		</description>
		</entry>
	</misc>
	<!--EXAMPLE-->
	<examplelist>
		<example img='live.remote~.png' />
	</examplelist>
	<!--SEEALSO-->
	<seealsolist>
		<seealso name='live_api_overview' module='core' type='vignette' display='Live API Overview'/>
		<seealso name='live_object_model' module='core' type='vignette' display='Live Object Model'/>
		<seealso name="live.object"/>
		<seealso name="live.observer"/>
		<seealso name="live.path"/>
		<seealso display="Using the Live API" module="core" name="live_api" type="vignette"/>
		<seealso display="The LiveAPI JavaScript Object (jsliveapi)" module="js" name="jsliveapi" type="vignette"/>
	</seealsolist>
</c74object>
